@effect-gql/persisted-queries 0.1.0 → 1.0.0

package/src/errors.ts

@@ -1,107 +0,0 @@
-import { Data } from "effect"
-
-/**
- * GraphQL error format for APQ responses.
- * Compatible with Apollo Client's error handling.
- */
-export interface PersistedQueryGraphQLError {
-  readonly message: string
-  readonly extensions: {
-    readonly code: string
-    readonly [key: string]: unknown
-  }
-}
-
-/**
- * Error returned when a persisted query hash is not found in the store
- * and no query body was provided.
- *
- * Apollo clients recognize this error and automatically retry with the full query.
- * This is the expected flow for Automatic Persisted Queries (APQ).
- */
-export class PersistedQueryNotFoundError extends Data.TaggedError("PersistedQueryNotFoundError")<{
-  readonly hash: string
-}> {
-  /**
-   * Convert to GraphQL error format compatible with Apollo protocol.
-   */
-  toGraphQLError(): PersistedQueryGraphQLError {
-    return {
-      message: "PersistedQueryNotFound",
-      extensions: {
-        code: "PERSISTED_QUERY_NOT_FOUND",
-      },
-    }
-  }
-}
-
-/**
- * Error returned when the persisted query protocol version is not supported.
- *
- * Currently only version 1 is supported, which uses SHA-256 hashing.
- */
-export class PersistedQueryVersionError extends Data.TaggedError("PersistedQueryVersionError")<{
-  readonly version: number
-}> {
-  toGraphQLError(): PersistedQueryGraphQLError {
-    return {
-      message: `Unsupported persisted query version: ${this.version}`,
-      extensions: {
-        code: "PERSISTED_QUERY_VERSION_NOT_SUPPORTED",
-        version: this.version,
-      },
-    }
-  }
-}
-
-/**
- * Error returned when the provided query doesn't match its hash.
- *
- * This can indicate a client bug or a potential hash collision attack.
- * Hash validation is enabled by default and can be disabled if needed.
- */
-export class PersistedQueryHashMismatchError extends Data.TaggedError(
-  "PersistedQueryHashMismatchError"
-)<{
-  readonly providedHash: string
-  readonly computedHash: string
-}> {
-  toGraphQLError(): PersistedQueryGraphQLError {
-    return {
-      message: "Query hash does not match provided hash",
-      extensions: {
-        code: "PERSISTED_QUERY_HASH_MISMATCH",
-      },
-    }
-  }
-}
-
-/**
- * Error returned when trying to execute a query that is not in the safelist.
- *
- * In safelist mode, only pre-registered queries are allowed.
- * This error is returned when a client tries to register a new query.
- */
-export class PersistedQueryNotAllowedError extends Data.TaggedError(
-  "PersistedQueryNotAllowedError"
-)<{
-  readonly hash: string
-}> {
-  toGraphQLError(): PersistedQueryGraphQLError {
-    return {
-      message: "Query not in safelist",
-      extensions: {
-        code: "PERSISTED_QUERY_NOT_ALLOWED",
-      },
-    }
-  }
-}
-
-/**
- * Union type of all APQ-related errors
- */
-export type PersistedQueryError =
-  | PersistedQueryNotFoundError
-  | PersistedQueryVersionError
-  | PersistedQueryHashMismatchError
-  | PersistedQueryNotAllowedError

package/src/index.ts

@@ -1,77 +0,0 @@
-/**
- * @effect-gql/persisted-queries
- *
- * Apollo Persisted Queries support for Effect GraphQL.
- *
- * Supports both Automatic Persisted Queries (APQ) mode for runtime registration
- * and Safelist mode for pre-registered query allowlisting.
- *
- * ## Quick Start
- *
- * @example APQ Mode (runtime registration)
- * ```typescript
- * import { makePersistedQueriesRouter } from "@effect-gql/persisted-queries"
- *
- * const router = makePersistedQueriesRouter(schema, serviceLayer, {
- *   mode: "apq",
- *   enableGet: true, // Enable CDN caching
- *   graphiql: { path: "/graphiql" },
- * })
- * ```
- *
- * @example Safelist Mode (pre-registered queries only)
- * ```typescript
- * import { makePersistedQueriesRouter, makeSafelistStore } from "@effect-gql/persisted-queries"
- *
- * const router = makePersistedQueriesRouter(schema, serviceLayer, {
- *   mode: "safelist",
- *   store: makeSafelistStore({
- *     "ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38": "query GetUser($id: ID!) { user(id: $id) { name email } }",
- *     "a1b2c3d4...": "query GetPosts { posts { title } }",
- *   }),
- * })
- * ```
- *
- * @example Custom Store Size
- * ```typescript
- * import { makePersistedQueriesRouter, makeMemoryStore } from "@effect-gql/persisted-queries"
- *
- * const router = makePersistedQueriesRouter(schema, serviceLayer, {
- *   store: makeMemoryStore({ maxSize: 5000 }),
- * })
- * ```
- *
- * @packageDocumentation
- */
-
-// Router
-export { makePersistedQueriesRouter } from "./persisted-queries-router"
-
-// Store interface and implementations
-export { PersistedQueryStore } from "./store"
-export type { PersistedQueryStore as PersistedQueryStoreInterface } from "./store"
-export { makeMemoryStore, makeSafelistStore } from "./memory-store"
-export type { MemoryStoreConfig } from "./memory-store"
-
-// Configuration
-export type {
-  PersistedQueriesConfig,
-  PersistedQueriesRouterOptions,
-  PersistedQueryMode,
-  HashAlgorithm,
-} from "./config"
-export { PersistedQueriesConfigFromEnv } from "./config"
-
-// Errors
-export {
-  PersistedQueryNotFoundError,
-  PersistedQueryVersionError,
-  PersistedQueryHashMismatchError,
-  PersistedQueryNotAllowedError,
-  type PersistedQueryError,
-  type PersistedQueryGraphQLError,
-} from "./errors"
-
-// Utilities
-export { computeHash, parsePersistedQueryExtension, parseGetRequestBody } from "./utils"
-export type { PersistedQueryExtension, GraphQLRequestBody } from "./utils"

package/src/memory-store.ts

@@ -1,133 +0,0 @@
-import { Effect, Layer, Option } from "effect"
-import { PersistedQueryStore } from "./store"
-
-/**
- * Configuration for the in-memory LRU store
- */
-export interface MemoryStoreConfig {
-  /**
-   * Maximum number of queries to cache.
-   * When exceeded, least recently used queries are evicted.
-   * Default: 1000
-   */
-  readonly maxSize?: number
-}
-
-/**
- * Create an in-memory LRU (Least Recently Used) store for persisted queries.
- *
- * This implementation uses Map's natural insertion order for O(1) LRU operations:
- * - get: O(1) - delete and re-insert to move to end (most recently used)
- * - set: O(1) - insert at end, evict from front if needed
- * - eviction: O(1) - delete first entry (least recently used)
- *
- * This is the default store implementation suitable for single-instance servers.
- * For multi-instance deployments, consider using a shared store like Redis.
- *
- * @param config - Optional configuration for cache size
- * @returns A Layer providing the PersistedQueryStore service
- *
- * @example
- * ```typescript
- * import { makeMemoryStore, makePersistedQueriesRouter } from "@effect-gql/persisted-queries"
- *
- * // Default store with 1000 entry limit
- * const router1 = makePersistedQueriesRouter(schema, serviceLayer)
- *
- * // Custom store with larger cache
- * const router2 = makePersistedQueriesRouter(schema, serviceLayer, {
- *   store: makeMemoryStore({ maxSize: 5000 })
- * })
- * ```
- */
-export const makeMemoryStore = (
-  config: MemoryStoreConfig = {}
-): Layer.Layer<PersistedQueryStore> => {
-  const maxSize = config.maxSize ?? 1000
-
-  // Map maintains insertion order - we use this for O(1) LRU
-  // First entry = least recently used, last entry = most recently used
-  const cache = new Map<string, string>()
-
-  // Move entry to end (most recently used) by deleting and re-inserting
-  const touch = (hash: string, query: string): void => {
-    cache.delete(hash)
-    cache.set(hash, query)
-  }
-
-  // Evict oldest entry (first in Map) if over capacity - O(1)
-  const evictIfNeeded = (): void => {
-    if (cache.size <= maxSize) return
-    // Map.keys().next() gives us the first (oldest) key in O(1)
-    const oldestKey = cache.keys().next().value
-    if (oldestKey !== undefined) {
-      cache.delete(oldestKey)
-    }
-  }
-
-  return Layer.succeed(
-    PersistedQueryStore,
-    PersistedQueryStore.of({
-      get: (hash) =>
-        Effect.sync(() => {
-          const query = cache.get(hash)
-          if (query === undefined) {
-            return Option.none<string>()
-          }
-          // Move to end (most recently used)
-          touch(hash, query)
-          return Option.some(query)
-        }),
-
-      set: (hash, query) =>
-        Effect.sync(() => {
-          // If key exists, delete first to ensure it moves to end
-          cache.delete(hash)
-          cache.set(hash, query)
-          evictIfNeeded()
-        }),
-
-      has: (hash) => Effect.sync(() => cache.has(hash)),
-    })
-  )
-}
-
-/**
- * Create a pre-populated safelist store.
- *
- * This store only allows queries that were provided at creation time.
- * Any attempt to store new queries is silently ignored.
- * Use this for production security where you want to allowlist specific operations.
- *
- * @param queries - Record mapping SHA-256 hashes to query strings
- * @returns A Layer providing the PersistedQueryStore service
- *
- * @example
- * ```typescript
- * import { makeSafelistStore, makePersistedQueriesRouter } from "@effect-gql/persisted-queries"
- *
- * // Pre-register allowed queries
- * const router = makePersistedQueriesRouter(schema, serviceLayer, {
- *   mode: "safelist",
- *   store: makeSafelistStore({
- *     "ecf4edb46db40b5132295c0291d62fb65d6759a9eedfa4d5d612dd5ec54a6b38": "query GetUser($id: ID!) { user(id: $id) { name email } }",
- *     "a1b2c3d4...": "query GetPosts { posts { title } }",
- *   }),
- * })
- * ```
- */
-export const makeSafelistStore = (
-  queries: Record<string, string>
-): Layer.Layer<PersistedQueryStore> =>
-  Layer.succeed(
-    PersistedQueryStore,
-    PersistedQueryStore.of({
-      get: (hash) =>
-        Effect.succeed(queries[hash] !== undefined ? Option.some(queries[hash]) : Option.none()),
-
-      // No-op for safelist mode - queries cannot be added at runtime
-      set: () => Effect.void,
-
-      has: (hash) => Effect.succeed(queries[hash] !== undefined),
-    })
-  )