@commitspark/graphql-api 2.0.0-beta.1 → 2.0.0-beta.2

package/src/graphql/input-type-generator.ts

@@ -14,10 +14,11 @@ import {
   isUnionType,
 } from 'graphql'
 import { SchemaAnalyzerResult } from './schema-analyzer.ts'
+import { buildsOnTypeWithEntryDirective } from './schema-utils/entry-type-util.ts'
 import {
-  buildsOnTypeWithEntryDirective,
-  hasEntryDirective,
-} from './schema-utils/entry-type-util.ts'
+  ENTRY_DIRECTIVE_NAME,
+  hasDirective,
+} from './schema-utils/directive-util.ts'
 
 function generateFieldInputTypeString(type: GraphQLNullableType): string {
   if (isListType(type)) {
@@ -25,7 +26,7 @@ function generateFieldInputTypeString(type: GraphQLNullableType): string {
   } else if (isNonNullType(type)) {
     return `${generateFieldInputTypeString(type.ofType)}!`
   } else if (isObjectType(type)) {
-    if (hasEntryDirective(type)) {
+    if (hasDirective(type, ENTRY_DIRECTIVE_NAME)) {
       return `${type.name}IdInput`
     } else {
       return `${type.name}Input`

package/src/graphql/queries-mutations-generator.ts

@@ -6,7 +6,11 @@ import { mutationCreateResolver } from './resolvers/query-mutation-resolvers/mut
 import { mutationUpdateResolver } from './resolvers/query-mutation-resolvers/mutation-update-resolver.ts'
 import { mutationDeleteResolver } from './resolvers/query-mutation-resolvers/mutation-delete-resolver.ts'
 import { queryTypeByIdResolver } from './resolvers/query-mutation-resolvers/query-type-by-id-resolver.ts'
-import { QueryMutationResolver } from './resolvers/types.ts'
+import { querySearchResolver } from './resolvers/query-mutation-resolvers/query-search-resolver.ts'
+import {
+  QueryMutationResolver,
+  SearchQueryResolver,
+} from './resolvers/types.ts'
 
 export function generateQueriesAndMutations(
   entryDirectiveTypes: GraphQLObjectType[],
@@ -122,6 +126,32 @@ export function generateTypeNameQuery(): GeneratedQuery {
   }
 }
 
+export function generateSearchQuery(): GeneratedSearchQuery {
+  const searchQueryName = '_search'
+  const searchHitTypeName = '_SearchHit'
+
+  return {
+    name: searchQueryName,
+    schemaString: `${searchQueryName}(query: String!, types: [String!], first: Int): [${searchHitTypeName}!]!`,
+    typeDefinitionString: `type ${searchHitTypeName} {
+  entryId: ID!
+  entryType: String!
+  fieldPath: String!
+  score: Float!
+  snippet: String!
+}
+`,
+    resolver: querySearchResolver,
+  }
+}
+
+export interface GeneratedSearchQuery {
+  name: string
+  schemaString: string
+  typeDefinitionString: string
+  resolver: SearchQueryResolver
+}
+
 export interface GeneratedSchema {
   queryEvery: GeneratedQuery
   queryById: GeneratedQuery

package/src/graphql/resolvers/field-resolvers/field-default-value-resolver.ts

@@ -7,10 +7,11 @@ import {
   isObjectType,
   isUnionType,
 } from 'graphql'
+import { buildsOnTypeWithEntryDirective } from '../../schema-utils/entry-type-util.ts'
 import {
-  buildsOnTypeWithEntryDirective,
-  hasEntryDirective,
-} from '../../schema-utils/entry-type-util.ts'
+  ENTRY_DIRECTIVE_NAME,
+  hasDirective,
+} from '../../schema-utils/directive-util.ts'
 import { resolveEntryReference } from './entry-reference-resolver.ts'
 import { resolveUnionValue } from './union-value-resolver.ts'
 import { createError, ErrorCode } from '../../errors.ts'
@@ -116,7 +117,7 @@ export const resolveFieldDefaultValue: FieldResolver = async (
       }
     }
 
-    if (hasEntryDirective(context.currentType)) {
+    if (hasDirective(context.currentType, ENTRY_DIRECTIVE_NAME)) {
       return resolveEntryReference(fieldValue, args, context, info)
     }
 

package/src/graphql/resolvers/query-mutation-resolvers/query-search-resolver.ts

@@ -0,0 +1,110 @@
+import { GraphQLError, GraphQLSchema, isObjectType } from 'graphql'
+import { SearchAdapterError, SearchHit } from '@commitspark/search-adapter'
+import { createError, ErrorCode } from '../../errors.ts'
+import {
+  ENTRY_DIRECTIVE_NAME,
+  hasDirective,
+} from '../../schema-utils/directive-util.ts'
+import { extractSearchableFieldValues } from '../../schema-utils/searchable-field-util.ts'
+import { SearchQueryResolver } from '../types.ts'
+
+const SEARCH_DEFAULT_LIMIT = 10
+const SEARCH_MAX_LIMIT = 100
+
+export const querySearchResolver: SearchQueryResolver = async (
+  _source,
+  args,
+  context,
+  info,
+) => {
+  const searchAdapter = context.searchAdapter
+  if (searchAdapter === undefined) {
+    throw createError(
+      'No search adapter configured.',
+      ErrorCode.INTERNAL_ERROR,
+      {},
+    )
+  }
+
+  if (args.query.trim() === '') {
+    throw createError(
+      'Search query must not be empty.',
+      ErrorCode.BAD_USER_INPUT,
+      {
+        argumentName: 'query',
+        argumentValue: args.query,
+      },
+    )
+  }
+
+  const limit = args.first ?? SEARCH_DEFAULT_LIMIT
+  if (limit < 1 || limit > SEARCH_MAX_LIMIT) {
+    throw createError(
+      `Argument "first" must be between 1 and ${SEARCH_MAX_LIMIT}.`,
+      ErrorCode.BAD_USER_INPUT,
+      {
+        argumentName: 'first',
+        argumentValue: limit,
+      },
+    )
+  }
+
+  const entryTypes = args.types ?? undefined
+  if (entryTypes !== undefined) {
+    validateEntryTypeNames(info.schema, entryTypes)
+    if (entryTypes.length === 0) {
+      return []
+    }
+  }
+
+  const commitHash = context.getCurrentHash()
+  let hits: SearchHit[]
+  try {
+    hits = await searchAdapter.search({
+      commitHash: commitHash,
+      query: args.query,
+      entryTypes: entryTypes,
+      limit: limit,
+      getSearchableFieldValues: async () => {
+        const entriesRecord = await context.repositoryCache.getEntriesRecord(
+          context,
+          commitHash,
+        )
+        return extractSearchableFieldValues(
+          info.schema,
+          entriesRecord.byId.values(),
+        )
+      },
+    })
+  } catch (err) {
+    if (err instanceof GraphQLError) {
+      throw err
+    }
+    if (err instanceof SearchAdapterError) {
+      throw createError(err.message, err.code, {})
+    }
+    const message = err instanceof Error ? err.message : String(err)
+    throw createError(message, ErrorCode.INTERNAL_ERROR, {})
+  }
+
+  return hits.slice(0, limit)
+}
+
+function validateEntryTypeNames(
+  schema: GraphQLSchema,
+  typeNames: string[],
+): void {
+  for (const typeName of typeNames) {
+    const type = schema.getType(typeName)
+    if (!isObjectType(type) || !hasDirective(type, ENTRY_DIRECTIVE_NAME)) {
+      throw createError(
+        `Type "${typeName}" is not an entry type.`,
+        ErrorCode.BAD_USER_INPUT,
+        {
+          argumentName: 'types',
+          argumentValue: typeName,
+        },
+      )
+    }
+  }
+}

package/src/graphql/resolvers/types.ts

@@ -5,6 +5,7 @@ import {
   GraphQLTypeResolver,
 } from 'graphql'
 import { EntryData } from '@commitspark/git-adapter'
+import { SearchHit } from '@commitspark/search-adapter'
 import { RecursiveArray } from './field-resolvers/types.ts'
 
 export interface QueryMutationResolverContext extends ApolloContext {
@@ -28,6 +29,13 @@ type UnionTypeResolverSourceData = EntryData & {
   __typename: string
 }
 
+export type SearchQueryResolver = GraphQLFieldResolver<
+  unknown,
+  ApolloContext,
+  { query: string; types?: string[] | null; first?: number | null },
+  Promise<SearchHit[]>
+>
+
 export type ContextInjectionResolver = GraphQLFieldResolver<
   EntryData,
   ApolloContext,

package/src/graphql/schema-analyzer.ts

@@ -8,6 +8,7 @@ import {
   isUnionType,
 } from 'graphql'
 import { getDirective } from '@graphql-tools/utils'
+import { ENTRY_DIRECTIVE_NAME } from './schema-utils/directive-util.ts'
 
 export function analyzeSchema(schema: GraphQLSchema): SchemaAnalyzerResult {
   const result: SchemaAnalyzerResult = {
@@ -27,7 +28,11 @@ export function analyzeSchema(schema: GraphQLSchema): SchemaAnalyzerResult {
     if (isObjectType(type)) {
       const objectType = type as GraphQLObjectType
       result.objectTypes.push(objectType)
-      const entityDirective = getDirective(schema, objectType, 'Entry')?.[0]
+      const entityDirective = getDirective(
+        schema,
+        objectType,
+        ENTRY_DIRECTIVE_NAME,
+      )?.[0]
       if (entityDirective) {
         result.entryDirectiveTypes.push(objectType)
       }

package/src/graphql/schema-generator.ts

@@ -1,5 +1,6 @@
 import {
   generateQueriesAndMutations,
+  generateSearchQuery,
   generateTypeNameQuery,
 } from './queries-mutations-generator.ts'
 import {
@@ -24,6 +25,7 @@ import { FieldResolver } from './resolvers/field-resolvers/types.ts'
 import {
   ContextInjectionResolver,
   QueryMutationResolver,
+  SearchQueryResolver,
   UnionTypeResolver,
 } from './resolvers/types.ts'
 import { EntryData } from '@commitspark/git-adapter'
@@ -57,6 +59,8 @@ export async function generateSchema(
     schemaAnalyzerResult.entryDirectiveTypes,
   )
   const generatedTypeNameQuery = generateTypeNameQuery()
+  const generatedSearchQuery =
+    context.searchAdapter !== undefined ? generateSearchQuery() : undefined
 
   const generatedObjectInputTypeStrings = generateObjectInputTypeStrings(
     schemaAnalyzerResult.objectTypes,
@@ -69,6 +73,7 @@ export async function generateSchema(
   const generatedSchemaRootTypeStrings = generateSchemaRootTypeStrings(
     generatedQueriesMutations,
     generatedTypeNameQuery,
+    generatedSearchQuery,
   )
 
   const generatedSchemaString = `schema {
@@ -92,7 +97,8 @@ ${generatedSchemaRootTypeStrings}`
 
   const generatedQueryResolvers: Record<
     string,
-    QueryMutationResolver<EntryData | EntryData[] | string>
+    | QueryMutationResolver<EntryData | EntryData[] | string>
+    | SearchQueryResolver
   > = {}
   const generatedMutationResolvers: Record<
     string,
@@ -112,12 +118,17 @@ ${generatedSchemaRootTypeStrings}`
   }
   generatedQueryResolvers[generatedTypeNameQuery.name] =
     generatedTypeNameQuery.resolver
+  if (generatedSearchQuery !== undefined) {
+    generatedQueryResolvers[generatedSearchQuery.name] =
+      generatedSearchQuery.resolver
+  }
 
   const allGeneratedResolvers: Record<
     string,
     | Record<
         string,
         | QueryMutationResolver<EntryData | EntryData[] | string>
+        | SearchQueryResolver
         | GraphQLTypeResolver<unknown, ApolloContext>
         | ContextInjectionResolver
         | FieldResolver
@@ -147,6 +158,7 @@ ${generatedSchemaRootTypeStrings}`
     generatedIdInputTypeStrings.join('\n'),
     generatedObjectInputTypeStrings.join('\n'),
     generatedUnionInputTypeStrings.join('\n'),
+    generatedSearchQuery?.typeDefinitionString ?? '',
   ].filter((typeDef) => typeDef.length > 0)
 
   return {

package/src/graphql/schema-root-type-generator.ts

@@ -1,11 +1,13 @@
 import {
   GeneratedQuery,
   GeneratedSchema,
+  GeneratedSearchQuery,
 } from './queries-mutations-generator.ts'
 
 export function generateSchemaRootTypeStrings(
   generatedSchemas: GeneratedSchema[],
   typeQuery: GeneratedQuery,
+  searchQuery: GeneratedSearchQuery | undefined,
 ): string {
   return (
     `type Query {\n` +
@@ -19,6 +21,7 @@ export function generateSchemaRootTypeStrings(
     '\n' +
     `  ${typeQuery.schemaString}` +
     '\n' +
+    (searchQuery !== undefined ? `  ${searchQuery.schemaString}\n` : '') +
     '}\n\n' +
     'type Mutation {\n' +
     generatedSchemas

package/src/graphql/schema-utils/directive-util.ts

@@ -0,0 +1,15 @@
+import { GraphQLField, GraphQLNamedType } from 'graphql'
+
+export const ENTRY_DIRECTIVE_NAME = 'Entry'
+export const SEARCHABLE_DIRECTIVE_NAME = 'Searchable'
+
+export function hasDirective(
+  typeOrField: GraphQLNamedType | GraphQLField<unknown, unknown>,
+  directiveName: string,
+): boolean {
+  return (
+    typeOrField.astNode?.directives?.some(
+      (directive) => directive.name.value === directiveName,
+    ) ?? false
+  )
+}

package/src/graphql/schema-utils/entry-reference-util.ts

@@ -14,7 +14,8 @@ import {
   getUnionTypeNameFromFieldValue,
   getUnionValue,
 } from './union-type-util.ts'
-import { hasEntryDirective, isUnionOfEntryTypes } from './entry-type-util.ts'
+import { ENTRY_DIRECTIVE_NAME, hasDirective } from './directive-util.ts'
+import { isUnionOfEntryTypes } from './entry-type-util.ts'
 import { createError, ErrorCode } from '../errors.ts'
 import { EntryData } from '@commitspark/git-adapter'
 import { isEntryData } from '../util.ts'
@@ -218,7 +219,10 @@ export async function getReferencedEntryIds(
   }
 
   if (isObjectType(type)) {
-    if (type.name !== rootType.name && hasEntryDirective(type)) {
+    if (
+      type.name !== rootType.name &&
+      hasDirective(type, ENTRY_DIRECTIVE_NAME)
+    ) {
       const referenceId = await getValidatedReferenceId(
         context,
         fieldName,

package/src/graphql/schema-utils/entry-type-util.ts

@@ -1,21 +1,12 @@
 import {
   GraphQLNullableType,
-  GraphQLObjectType,
   GraphQLUnionType,
   isListType,
   isNonNullType,
   isObjectType,
   isUnionType,
 } from 'graphql'
-
-export function hasEntryDirective(type: GraphQLObjectType): boolean {
-  return (
-    !!type.astNode &&
-    type.astNode.directives?.find(
-      (directive) => directive.name.value === 'Entry',
-    ) !== undefined
-  )
-}
+import { ENTRY_DIRECTIVE_NAME, hasDirective } from './directive-util.ts'
 
 export function isUnionOfEntryTypes(type: GraphQLUnionType): boolean {
   return type
@@ -33,7 +24,7 @@ export function buildsOnTypeWithEntryDirective(
   } else if (isUnionType(type)) {
     return isUnionOfEntryTypes(type)
   } else if (isObjectType(type)) {
-    return hasEntryDirective(type)
+    return hasDirective(type, ENTRY_DIRECTIVE_NAME)
   }
   return false
 }

package/src/graphql/schema-utils/searchable-field-util.ts

@@ -0,0 +1,130 @@
+import {
+  GraphQLObjectType,
+  GraphQLOutputType,
+  GraphQLSchema,
+  isListType,
+  isNonNullType,
+  isObjectType,
+  isScalarType,
+  isUnionType,
+} from 'graphql'
+import { Entry } from '@commitspark/git-adapter'
+import { SearchableFieldValue } from '@commitspark/search-adapter'
+import {
+  ENTRY_DIRECTIVE_NAME,
+  hasDirective,
+  SEARCHABLE_DIRECTIVE_NAME,
+} from './directive-util.ts'
+import { isUnionOfEntryTypes } from './entry-type-util.ts'
+import { getUnionTypeNameFromFieldValue } from './union-type-util.ts'
+
+// Returns every non-empty string value of searchable fields. Values that do not match the schema are skipped instead
+// of failing the search.
+export function extractSearchableFieldValues(
+  schema: GraphQLSchema,
+  entries: Iterable<Entry>,
+): SearchableFieldValue[] {
+  const searchableFieldValues: SearchableFieldValue[] = []
+  for (const entry of entries) {
+    const entryType = schema.getType(entry.metadata.type)
+    if (!isObjectType(entryType) || !isRecord(entry.data)) {
+      continue
+    }
+    const addValue = (fieldPath: string, value: string): void => {
+      searchableFieldValues.push({
+        entryId: entry.id,
+        entryType: entryType.name,
+        fieldPath: fieldPath,
+        value: value,
+      })
+    }
+    collectFromObject(schema, entryType, entry.data, '', addValue)
+  }
+  return searchableFieldValues
+}
+
+function collectFromObject(
+  schema: GraphQLSchema,
+  objectType: GraphQLObjectType,
+  data: Record<string, unknown>,
+  path: string,
+  addValue: (fieldPath: string, value: string) => void,
+): void {
+  const isTypeSearchable = hasDirective(objectType, SEARCHABLE_DIRECTIVE_NAME)
+  for (const field of Object.values(objectType.getFields())) {
+    const value = data[field.name]
+    if (value === undefined || value === null) {
+      continue
+    }
+    collectFromValue(
+      schema,
+      field.type,
+      value,
+      path === '' ? field.name : `${path}.${field.name}`,
+      isTypeSearchable || hasDirective(field, SEARCHABLE_DIRECTIVE_NAME),
+      addValue,
+    )
+  }
+}
+
+function collectFromValue(
+  schema: GraphQLSchema,
+  type: GraphQLOutputType,
+  value: unknown,
+  path: string,
+  isSearchable: boolean,
+  addValue: (fieldPath: string, value: string) => void,
+): void {
+  if (isNonNullType(type)) {
+    collectFromValue(schema, type.ofType, value, path, isSearchable, addValue)
+  } else if (isListType(type)) {
+    if (!Array.isArray(value)) {
+      return
+    }
+    value.forEach((item, index) =>
+      collectFromValue(
+        schema,
+        type.ofType,
+        item,
+        `${path}[${index}]`,
+        isSearchable,
+        addValue,
+      ),
+    )
+  } else if (isScalarType(type)) {
+    if (
+      isSearchable &&
+      type.name === 'String' &&
+      typeof value === 'string' &&
+      value.trim() !== ''
+    ) {
+      addValue(path, value)
+    }
+  } else if (isObjectType(type)) {
+    // references to other entries are not followed, as each entry is indexed with its own content only
+    if (!hasDirective(type, ENTRY_DIRECTIVE_NAME) && isRecord(value)) {
+      collectFromObject(schema, type, value, path, addValue)
+    }
+  } else if (isUnionType(type)) {
+    if (isUnionOfEntryTypes(type) || !isRecord(value)) {
+      return
+    }
+    // non-entry union values are stored wrapped in an object keyed by their concrete type name, which is kept in the
+    // path so that the path matches stored data and identifies the concrete type
+    const concreteType = schema.getType(getUnionTypeNameFromFieldValue(value))
+    const concreteValue = value[concreteType?.name ?? '']
+    if (isObjectType(concreteType) && isRecord(concreteValue)) {
+      collectFromObject(
+        schema,
+        concreteType,
+        concreteValue,
+        `${path}.${concreteType.name}`,
+        addValue,
+      )
+    }
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/graphql/schema-validator.ts

@@ -1,4 +1,16 @@
-import { GraphQLSchema, GraphQLUnionType, Kind } from 'graphql'
+import {
+  getNamedType,
+  GraphQLSchema,
+  GraphQLUnionType,
+  isObjectType,
+  isScalarType,
+  Kind,
+} from 'graphql'
+import {
+  ENTRY_DIRECTIVE_NAME,
+  hasDirective,
+  SEARCHABLE_DIRECTIVE_NAME,
+} from './schema-utils/directive-util.ts'
 
 function checkUnionMembersConsistentUseOfEntryDirective(
   schema: GraphQLSchema,
@@ -12,18 +24,35 @@ function checkUnionMembersConsistentUseOfEntryDirective(
     const innerTypes = (type as GraphQLUnionType).getTypes()
 
     const numberUnionMembersWithEntryDirective = innerTypes.filter(
-      (innerType) =>
-        !!innerType.astNode &&
-        innerType.astNode.directives?.find(
-          (directive) => directive.name.value === 'Entry',
-        ) !== undefined,
+      (innerType) => hasDirective(innerType, ENTRY_DIRECTIVE_NAME),
     ).length
 
     if (
       numberUnionMembersWithEntryDirective !== 0 &&
       numberUnionMembersWithEntryDirective !== innerTypes.length
     ) {
-      return `Either all union members of "${type.name}" must have "@Entry" directive or none.`
+      return `Either all union members of "${type.name}" must have "@${ENTRY_DIRECTIVE_NAME}" directive or none.`
+    }
+  }
+
+  return ''
+}
+
+function checkSearchableDirectiveOnlyOnStringFields(
+  schema: GraphQLSchema,
+): string {
+  for (const type of Object.values(schema.getTypeMap())) {
+    if (!isObjectType(type) || type.name.startsWith('__')) {
+      continue
+    }
+    for (const field of Object.values(type.getFields())) {
+      if (!hasDirective(field, SEARCHABLE_DIRECTIVE_NAME)) {
+        continue
+      }
+      const namedType = getNamedType(field.type)
+      if (!isScalarType(namedType) || namedType.name !== 'String') {
+        return `Field "${type.name}.${field.name}" must be of type "String" or a list of "String" to use "@${SEARCHABLE_DIRECTIVE_NAME}" directive.`
+      }
     }
   }
 
@@ -33,5 +62,6 @@ function checkUnionMembersConsistentUseOfEntryDirective(
 export function getValidationResult(schema: GraphQLSchema): string[] {
   const results = []
   results.push(checkUnionMembersConsistentUseOfEntryDirective(schema))
+  results.push(checkSearchableDirectiveOnlyOnStringFields(schema))
   return results.filter((result) => result !== '')
 }

package/src/index.ts

@@ -7,6 +7,7 @@ import {
   VariableValues,
 } from './client.ts'
 import { GitAdapter } from '@commitspark/git-adapter'
+import { SearchAdapter } from '@commitspark/search-adapter'
 import { ErrorCode, ErrorMetadata } from './graphql/errors.ts'
 import { createCacheHandler } from './persistence/cache.ts'
 
@@ -21,12 +22,32 @@ interface Client {
   getSchema(ref: string): Promise<SchemaResponse>
 }
 
-export { Client, GraphQLResponse, SchemaResponse, ErrorCode, ErrorMetadata }
+interface ClientOptions {
+  /**
+   * Enables query `_search` when set.
+   */
+  searchAdapter?: SearchAdapter
+}
+
+export {
+  Client,
+  ClientOptions,
+  GraphQLResponse,
+  SchemaResponse,
+  ErrorCode,
+  ErrorMetadata,
+}
 
-export async function createClient(gitAdapter: GitAdapter): Promise<Client> {
+export async function createClient(
+  gitAdapter: GitAdapter,
+  options: ClientOptions = {},
+): Promise<Client> {
   const repositoryCache = createCacheHandler()
+  const searchAdapter = options.searchAdapter
   return {
-    postGraphQL: (...args) => postGraphQL(gitAdapter, repositoryCache, ...args),
-    getSchema: (...args) => getSchema(gitAdapter, repositoryCache, ...args),
+    postGraphQL: (...args) =>
+      postGraphQL(gitAdapter, searchAdapter, repositoryCache, ...args),
+    getSchema: (...args) =>
+      getSchema(gitAdapter, searchAdapter, repositoryCache, ...args),
   }
 }