@ankhorage/data-sources 1.0.1 → 2.0.1

package/src/graphql/index.ts

@@ -1,18 +1,24 @@
 import type {
-  CredentialRef,
-  DataContractValue,
   DataEndpointConfig,
-  DataOperationConfig,
-  DataOperationIntent,
-  DataOperationResponse,
-  DataSchema,
-  DataSchemaRegistry,
   DataSourceDiagnostic,
   DataSourceDiagnosticResult,
-  ExternalGraphQlApiDataSourceConfig,
-  OperationId,
+  ExternalGraphQlApiDefinition,
 } from '@ankhorage/contracts/data';
 
+import {
+  normalizeGraphQlIntrospectionOperations,
+  normalizeGraphQlIntrospectionSchemas,
+} from './introspection';
+import { normalizeGraphQlOperation } from './operation';
+import type { GraphQlApiDefinition } from './types';
+
+export {
+  normalizeGraphQlIntrospectionOperations,
+  normalizeGraphQlIntrospectionSchemas,
+} from './introspection';
+export { normalizeGraphQlOperationId } from './operation';
+export type * from './types';
+
 export const GRAPHQL_INTROSPECTION_QUERY = `query AnkhorageGraphQlIntrospection {
   __schema {
     queryType { name }
@@ -45,80 +51,6 @@ export const GRAPHQL_INTROSPECTION_QUERY = `query AnkhorageGraphQlIntrospection
   }
 }`;
 
-export type GraphQlOperationKind = 'mutation' | 'query' | 'subscription';
-type DataContractRecord = Record<string, DataContractValue>;
-
-export interface GraphQlIntrospectionTypeRef {
-  readonly kind: string;
-  readonly name?: string | null;
-  readonly ofType?: GraphQlIntrospectionTypeRef | null;
-}
-
-export interface GraphQlIntrospectionInputValue {
-  readonly name: string;
-  readonly description?: string | null;
-  readonly type: GraphQlIntrospectionTypeRef;
-  readonly defaultValue?: string | null;
-}
-
-export interface GraphQlIntrospectionField {
-  readonly name: string;
-  readonly description?: string | null;
-  readonly args?: readonly GraphQlIntrospectionInputValue[] | null;
-  readonly type: GraphQlIntrospectionTypeRef;
-}
-
-export interface GraphQlIntrospectionEnumValue {
-  readonly name: string;
-  readonly description?: string | null;
-}
-
-export interface GraphQlIntrospectionType {
-  readonly kind: string;
-  readonly name?: string | null;
-  readonly description?: string | null;
-  readonly fields?: readonly GraphQlIntrospectionField[] | null;
-  readonly inputFields?: readonly GraphQlIntrospectionInputValue[] | null;
-  readonly enumValues?: readonly GraphQlIntrospectionEnumValue[] | null;
-  readonly possibleTypes?: readonly GraphQlIntrospectionTypeRef[] | null;
-}
-
-export interface GraphQlIntrospectionSchema {
-  readonly queryType?: { readonly name?: string | null } | null;
-  readonly mutationType?: { readonly name?: string | null } | null;
-  readonly subscriptionType?: { readonly name?: string | null } | null;
-  readonly types?: readonly GraphQlIntrospectionType[] | null;
-}
-
-export interface GraphQlIntrospectionResult {
-  readonly __schema?: GraphQlIntrospectionSchema;
-}
-
-export interface GraphQlOperationDefinition {
-  readonly id: OperationId;
-  readonly kind: GraphQlOperationKind;
-  readonly name?: string;
-  readonly description?: string;
-  readonly document?: string;
-  readonly variables?: DataSchema;
-  readonly response?: DataSchema;
-  readonly selectionPath?: string;
-  readonly metadata?: DataContractValue;
-}
-
-export interface GraphQlDataSourceDefinition {
-  readonly id: string;
-  readonly endpointUrl: string;
-  readonly name?: string;
-  readonly description?: string;
-  readonly credential?: CredentialRef;
-  readonly introspection?: GraphQlIntrospectionResult;
-  readonly introspectionEnabled?: boolean;
-  readonly schemaVersion?: string;
-  readonly operations?: readonly GraphQlOperationDefinition[];
-  readonly metadata?: DataContractValue;
-}
-
 export interface GraphQlIntrospectionRequest {
   readonly query: typeof GRAPHQL_INTROSPECTION_QUERY;
   readonly operationName: 'AnkhorageGraphQlIntrospection';
@@ -131,91 +63,72 @@ export function createGraphQlIntrospectionRequest(): GraphQlIntrospectionRequest
   };
 }
 
-export function normalizeGraphQlOperationId(kind: GraphQlOperationKind, name: string): OperationId {
-  const normalizedName = name
-    .replace(/[^A-Za-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .toLowerCase();
-  return normalizedName.length > 0 ? `${kind}.${normalizedName}` : `${kind}.operation`;
-}
-
-export function createGraphQlDataSource(
-  definition: GraphQlDataSourceDefinition,
-): DataSourceDiagnosticResult<ExternalGraphQlApiDataSourceConfig> {
-  const diagnostics = validateGraphQlDataSource(definition);
+export function createGraphQlApi(
+  definition: GraphQlApiDefinition,
+): DataSourceDiagnosticResult<ExternalGraphQlApiDefinition> {
+  const diagnostics = validateGraphQlApi(definition);
   if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
     return { ok: false, diagnostics };
   }
-
-  return {
-    ok: true,
-    data: normalizeGraphQlDataSource(definition),
-    diagnostics,
-  };
+  return { ok: true, data: normalizeGraphQlApi(definition), diagnostics };
 }
 
-export function validateGraphQlDataSource(
-  definition: GraphQlDataSourceDefinition,
+export function validateGraphQlApi(
+  definition: GraphQlApiDefinition,
 ): readonly DataSourceDiagnostic[] {
   const diagnostics: DataSourceDiagnostic[] = [];
 
   if (definition.endpointUrl.trim().length === 0) {
     diagnostics.push({
       code: 'invalid-config',
-      dataSourceId: definition.id,
-      message: 'GraphQL data source requires a non-empty endpointUrl.',
+      apiId: definition.id,
+      message: 'GraphQL API requires a non-empty endpointUrl.',
       path: 'endpointUrl',
       severity: 'error',
     });
   }
-
   if (definition.introspectionEnabled === false && definition.introspection !== undefined) {
     diagnostics.push({
       code: 'invalid-config',
-      dataSourceId: definition.id,
+      apiId: definition.id,
       message: 'GraphQL introspection data was provided while introspection is disabled.',
       path: 'introspection',
       severity: 'warning',
     });
   }
-
   if (definition.introspectionEnabled !== false && definition.introspection === undefined) {
     diagnostics.push({
       code: 'missing-schema',
-      dataSourceId: definition.id,
+      apiId: definition.id,
       message:
         'GraphQL introspection result was not provided. Manual operations can still be used.',
       path: 'introspection',
       severity: 'info',
     });
   }
-
   return diagnostics;
 }
 
-export function normalizeGraphQlDataSource(
-  definition: GraphQlDataSourceDefinition,
-): ExternalGraphQlApiDataSourceConfig {
+export function normalizeGraphQlApi(
+  definition: GraphQlApiDefinition,
+): ExternalGraphQlApiDefinition {
   const schemas = normalizeGraphQlIntrospectionSchemas(definition.introspection);
   const discovered = normalizeGraphQlIntrospectionOperations(definition.introspection);
-  const operations: Record<OperationId, DataOperationConfig> = {};
-
-  for (const operation of [...discovered, ...(definition.operations ?? [])]) {
-    operations[operation.id] = normalizeGraphQlOperation(operation);
-  }
-
+  const operations = Object.fromEntries(
+    [...discovered, ...(definition.operations ?? [])].map((operation) => [
+      operation.id,
+      normalizeGraphQlOperation(operation),
+    ]),
+  );
   const endpoint: DataEndpointConfig = {
     id: 'graphql',
     kind: 'graphql',
-    baseUrl: definition.endpointUrl,
     credential: definition.credential,
     operations,
     metadata: { source: 'graphql' },
   };
-
   return {
     id: definition.id,
-    kind: 'api',
     origin: 'external',
     protocol: 'graphql',
     name: definition.name,
@@ -231,196 +144,3 @@ export function normalizeGraphQlDataSource(
     metadata: definition.metadata,
   };
 }
-
-export function normalizeGraphQlIntrospectionSchemas(
-  introspection: GraphQlIntrospectionResult | undefined,
-): DataSchemaRegistry | undefined {
-  const types = introspection?.__schema?.types?.filter(isNamedGraphQlType) ?? [];
-  if (types.length === 0) return undefined;
-
-  const schemas: Record<string, DataSchema> = {};
-  for (const type of types) {
-    if (type.name === undefined || type.name === null || type.name.startsWith('__')) continue;
-    schemas[type.name] = normalizeGraphQlType(type);
-  }
-  return schemas;
-}
-
-export function normalizeGraphQlIntrospectionOperations(
-  introspection: GraphQlIntrospectionResult | undefined,
-): readonly GraphQlOperationDefinition[] {
-  const schema = introspection?.__schema;
-  if (schema === undefined) return [];
-
-  const types = schema.types?.filter(isNamedGraphQlType) ?? [];
-  const operations: GraphQlOperationDefinition[] = [];
-  appendRootOperations(operations, 'query', schema.queryType?.name, types);
-  appendRootOperations(operations, 'mutation', schema.mutationType?.name, types);
-  appendRootOperations(operations, 'subscription', schema.subscriptionType?.name, types);
-  return operations;
-}
-
-function appendRootOperations(
-  operations: GraphQlOperationDefinition[],
-  kind: GraphQlOperationKind,
-  rootTypeName: string | null | undefined,
-  types: readonly GraphQlIntrospectionType[],
-): void {
-  if (rootTypeName === undefined || rootTypeName === null) return;
-  const rootType = types.find((type) => type.name === rootTypeName);
-
-  for (const field of rootType?.fields ?? []) {
-    operations.push({
-      id: normalizeGraphQlOperationId(kind, field.name),
-      kind,
-      name: field.name,
-      description: field.description ?? undefined,
-      variables: normalizeGraphQlVariablesSchema(field.args ?? []),
-      response: normalizeGraphQlTypeRef(field.type),
-      selectionPath: `$.data.${field.name}`,
-      metadata: { rootType: rootTypeName, source: 'introspection' },
-    });
-  }
-}
-
-function normalizeGraphQlOperation(operation: GraphQlOperationDefinition): DataOperationConfig {
-  const response: DataOperationResponse | undefined =
-    operation.response === undefined ? undefined : { schema: operation.response };
-
-  return {
-    id: operation.id,
-    endpointId: 'graphql',
-    name: operation.name,
-    description: operation.description,
-    protocol: 'graphql',
-    intent: mapGraphQlOperationKindToIntent(operation.kind),
-    request: { schema: operation.variables },
-    response,
-    metadata: createGraphQlOperationMetadata(operation),
-  };
-}
-
-function mapGraphQlOperationKindToIntent(kind: GraphQlOperationKind): DataOperationIntent {
-  return kind === 'query' || kind === 'subscription' ? 'read' : 'action';
-}
-
-function normalizeGraphQlVariablesSchema(
-  args: readonly GraphQlIntrospectionInputValue[],
-): DataSchema {
-  const properties: Record<string, DataSchema> = {};
-  const required: string[] = [];
-
-  for (const arg of args) {
-    properties[arg.name] = {
-      ...normalizeGraphQlTypeRef(arg.type),
-      description: arg.description ?? undefined,
-      default: arg.defaultValue ?? undefined,
-    };
-    if (isGraphQlNonNull(arg.type)) required.push(arg.name);
-  }
-
-  return {
-    type: 'object',
-    required: required.length > 0 ? required : undefined,
-    properties,
-  };
-}
-
-function normalizeGraphQlType(type: GraphQlIntrospectionType): DataSchema {
-  if (type.kind === 'OBJECT' || type.kind === 'INTERFACE' || type.kind === 'INPUT_OBJECT') {
-    return normalizeGraphQlObjectType(type);
-  }
-  if (type.kind === 'ENUM') {
-    return {
-      type: 'string',
-      title: type.name ?? undefined,
-      description: type.description ?? undefined,
-      enum: type.enumValues?.map((value) => value.name),
-    };
-  }
-  if (type.kind === 'SCALAR') {
-    return {
-      ...normalizeGraphQlNamedScalar(type.name),
-      title: type.name ?? undefined,
-      description: type.description ?? undefined,
-    };
-  }
-  if (type.kind === 'UNION') {
-    return {
-      title: type.name ?? undefined,
-      description: type.description ?? undefined,
-      anyOf: type.possibleTypes?.map(normalizeGraphQlTypeRef),
-    };
-  }
-  return { title: type.name ?? undefined, description: type.description ?? undefined };
-}
-
-function normalizeGraphQlObjectType(type: GraphQlIntrospectionType): DataSchema {
-  const fields = type.kind === 'INPUT_OBJECT' ? type.inputFields : type.fields;
-  const properties: Record<string, DataSchema> = {};
-  const required: string[] = [];
-
-  for (const field of fields ?? []) {
-    const fieldType = field.type;
-    properties[field.name] = {
-      ...normalizeGraphQlTypeRef(fieldType),
-      description: field.description ?? undefined,
-    };
-    if (isGraphQlNonNull(fieldType)) required.push(field.name);
-  }
-
-  return {
-    type: 'object',
-    title: type.name ?? undefined,
-    description: type.description ?? undefined,
-    required: required.length > 0 ? required : undefined,
-    properties,
-  };
-}
-
-function normalizeGraphQlTypeRef(type: GraphQlIntrospectionTypeRef): DataSchema {
-  if (type.kind === 'NON_NULL' && type.ofType !== undefined && type.ofType !== null) {
-    return { ...normalizeGraphQlTypeRef(type.ofType), nullable: false };
-  }
-  if (type.kind === 'LIST' && type.ofType !== undefined && type.ofType !== null) {
-    return { type: 'array', items: normalizeGraphQlTypeRef(type.ofType) };
-  }
-  if (type.kind === 'SCALAR') return normalizeGraphQlNamedScalar(type.name);
-  if (type.name !== undefined && type.name !== null) return { ref: { id: type.name } };
-  return {};
-}
-
-function normalizeGraphQlNamedScalar(name: string | null | undefined): DataSchema {
-  if (name === 'Boolean') return { type: 'boolean' };
-  if (name === 'Float') return { type: 'number' };
-  if (name === 'ID' || name === 'String') return { type: 'string' };
-  if (name === 'Int') return { type: 'integer' };
-  return { type: 'string', format: name ?? undefined };
-}
-
-function isGraphQlNonNull(type: GraphQlIntrospectionTypeRef): boolean {
-  return type.kind === 'NON_NULL';
-}
-
-function isNamedGraphQlType(type: GraphQlIntrospectionType): boolean {
-  return type.name !== undefined && type.name !== null;
-}
-
-function createGraphQlOperationMetadata(operation: GraphQlOperationDefinition): DataContractRecord {
-  const metadata = toMetadataRecord(operation.metadata);
-  metadata.kind = operation.kind;
-  if (operation.document !== undefined) metadata.document = operation.document;
-  if (operation.selectionPath !== undefined) metadata.selectionPath = operation.selectionPath;
-  return metadata;
-}
-
-function toMetadataRecord(value: DataContractValue | undefined): DataContractRecord {
-  if (!isDataContractRecord(value)) return {};
-  return { ...value };
-}
-
-function isDataContractRecord(value: DataContractValue | undefined): value is DataContractRecord {
-  return (
-    value !== undefined && typeof value === 'object' && value !== null && !Array.isArray(value)
-  );
-}

package/src/graphql/introspection.ts

@@ -0,0 +1,163 @@
+import type { DataSchema, DataSchemaRegistry } from '@ankhorage/contracts/data';
+
+import { normalizeGraphQlOperationId } from './operation';
+import type {
+  GraphQlIntrospectionInputValue,
+  GraphQlIntrospectionResult,
+  GraphQlIntrospectionType,
+  GraphQlIntrospectionTypeRef,
+  GraphQlOperationDefinition,
+  GraphQlOperationKind,
+} from './types';
+
+const OBJECT_TYPE_KINDS = new Set(['OBJECT', 'INTERFACE', 'INPUT_OBJECT']);
+
+export function normalizeGraphQlIntrospectionSchemas(
+  introspection: GraphQlIntrospectionResult | undefined,
+): DataSchemaRegistry | undefined {
+  const types = introspection?.__schema?.types?.filter(isNamedGraphQlType) ?? [];
+  const entries = types.flatMap((type) => {
+    const { name } = type;
+    if (name === undefined || name === null || name.startsWith('__')) return [];
+    return [[name, normalizeGraphQlType(type)] as const];
+  });
+  return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}
+
+export function normalizeGraphQlIntrospectionOperations(
+  introspection: GraphQlIntrospectionResult | undefined,
+): readonly GraphQlOperationDefinition[] {
+  const schema = introspection?.__schema;
+  if (schema === undefined) return [];
+
+  const types = schema.types?.filter(isNamedGraphQlType) ?? [];
+  return [
+    ...normalizeRootOperations('query', schema.queryType?.name, types),
+    ...normalizeRootOperations('mutation', schema.mutationType?.name, types),
+    ...normalizeRootOperations('subscription', schema.subscriptionType?.name, types),
+  ];
+}
+
+function normalizeRootOperations(
+  kind: GraphQlOperationKind,
+  rootTypeName: string | null | undefined,
+  types: readonly GraphQlIntrospectionType[],
+): readonly GraphQlOperationDefinition[] {
+  if (rootTypeName === undefined || rootTypeName === null) return [];
+  const rootType = types.find((type) => type.name === rootTypeName);
+  return (rootType?.fields ?? []).map((field) => ({
+    id: normalizeGraphQlOperationId(kind, field.name),
+    kind,
+    name: field.name,
+    description: field.description ?? undefined,
+    variables: normalizeGraphQlVariablesSchema(field.args ?? []),
+    response: normalizeGraphQlTypeRef(field.type),
+    selectionPath: `$.data.${field.name}`,
+    metadata: { rootType: rootTypeName, source: 'introspection' },
+  }));
+}
+
+function normalizeGraphQlVariablesSchema(
+  args: readonly GraphQlIntrospectionInputValue[],
+): DataSchema {
+  const properties = Object.fromEntries(
+    args.map((arg) => [
+      arg.name,
+      {
+        ...normalizeGraphQlTypeRef(arg.type),
+        description: arg.description ?? undefined,
+        default: arg.defaultValue ?? undefined,
+      },
+    ]),
+  );
+  const required = args.filter((arg) => isGraphQlNonNull(arg.type)).map((arg) => arg.name);
+  return {
+    type: 'object',
+    required: required.length > 0 ? required : undefined,
+    properties,
+  };
+}
+
+function normalizeGraphQlType(type: GraphQlIntrospectionType): DataSchema {
+  if (OBJECT_TYPE_KINDS.has(type.kind)) return normalizeGraphQlObjectType(type);
+  if (type.kind === 'ENUM') return normalizeGraphQlEnumType(type);
+  if (type.kind === 'SCALAR') return normalizeGraphQlScalarType(type);
+  if (type.kind === 'UNION') return normalizeGraphQlUnionType(type);
+  return { title: type.name ?? undefined, description: type.description ?? undefined };
+}
+
+function normalizeGraphQlEnumType(type: GraphQlIntrospectionType): DataSchema {
+  return {
+    type: 'string',
+    title: type.name ?? undefined,
+    description: type.description ?? undefined,
+    enum: type.enumValues?.map((value) => value.name),
+  };
+}
+
+function normalizeGraphQlScalarType(type: GraphQlIntrospectionType): DataSchema {
+  return {
+    ...normalizeGraphQlNamedScalar(type.name),
+    title: type.name ?? undefined,
+    description: type.description ?? undefined,
+  };
+}
+
+function normalizeGraphQlUnionType(type: GraphQlIntrospectionType): DataSchema {
+  return {
+    title: type.name ?? undefined,
+    description: type.description ?? undefined,
+    anyOf: type.possibleTypes?.map(normalizeGraphQlTypeRef),
+  };
+}
+
+function normalizeGraphQlObjectType(type: GraphQlIntrospectionType): DataSchema {
+  const fields = type.kind === 'INPUT_OBJECT' ? type.inputFields : type.fields;
+  const entries = (fields ?? []).map(
+    (field) =>
+      [
+        field.name,
+        {
+          ...normalizeGraphQlTypeRef(field.type),
+          description: field.description ?? undefined,
+        },
+      ] as const,
+  );
+  const required = (fields ?? [])
+    .filter((field) => isGraphQlNonNull(field.type))
+    .map((field) => field.name);
+  return {
+    type: 'object',
+    title: type.name ?? undefined,
+    description: type.description ?? undefined,
+    required: required.length > 0 ? required : undefined,
+    properties: Object.fromEntries(entries),
+  };
+}
+
+function normalizeGraphQlTypeRef(type: GraphQlIntrospectionTypeRef): DataSchema {
+  if (type.kind === 'NON_NULL' && type.ofType !== undefined && type.ofType !== null) {
+    return { ...normalizeGraphQlTypeRef(type.ofType), nullable: false };
+  }
+  if (type.kind === 'LIST' && type.ofType !== undefined && type.ofType !== null) {
+    return { type: 'array', items: normalizeGraphQlTypeRef(type.ofType) };
+  }
+  if (type.kind === 'SCALAR') return normalizeGraphQlNamedScalar(type.name);
+  return type.name === undefined || type.name === null ? {} : { ref: { id: type.name } };
+}
+
+function normalizeGraphQlNamedScalar(name: string | null | undefined): DataSchema {
+  if (name === 'Boolean') return { type: 'boolean' };
+  if (name === 'Float') return { type: 'number' };
+  if (name === 'ID' || name === 'String') return { type: 'string' };
+  if (name === 'Int') return { type: 'integer' };
+  return { type: 'string', format: name ?? undefined };
+}
+
+function isGraphQlNonNull(type: GraphQlIntrospectionTypeRef): boolean {
+  return type.kind === 'NON_NULL';
+}
+
+function isNamedGraphQlType(type: GraphQlIntrospectionType): boolean {
+  return type.name !== undefined && type.name !== null;
+}

package/src/graphql/operation.ts

@@ -0,0 +1,60 @@
+import type {
+  DataContractValue,
+  DataOperationConfig,
+  DataOperationIntent,
+  DataOperationResponse,
+  OperationId,
+} from '@ankhorage/contracts/data';
+
+import type { GraphQlOperationDefinition, GraphQlOperationKind } from './types';
+
+type DataContractRecord = Record<string, DataContractValue>;
+
+export function normalizeGraphQlOperationId(kind: GraphQlOperationKind, name: string): OperationId {
+  const normalizedName = name
+    .replace(/[^A-Za-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+  return normalizedName.length > 0 ? `${kind}.${normalizedName}` : `${kind}.operation`;
+}
+
+export function normalizeGraphQlOperation(
+  operation: GraphQlOperationDefinition,
+): DataOperationConfig {
+  const response: DataOperationResponse | undefined =
+    operation.response === undefined ? undefined : { schema: operation.response };
+  return {
+    id: operation.id,
+    endpointId: 'graphql',
+    name: operation.name,
+    description: operation.description,
+    protocol: 'graphql',
+    intent: mapGraphQlOperationKindToIntent(operation.kind),
+    request: { schema: operation.variables },
+    response,
+    metadata: createGraphQlOperationMetadata(operation),
+  };
+}
+
+function mapGraphQlOperationKindToIntent(kind: GraphQlOperationKind): DataOperationIntent {
+  return kind === 'query' || kind === 'subscription' ? 'read' : 'action';
+}
+
+function createGraphQlOperationMetadata(operation: GraphQlOperationDefinition): DataContractRecord {
+  return {
+    ...toMetadataRecord(operation.metadata),
+    kind: operation.kind,
+    ...(operation.document === undefined ? {} : { document: operation.document }),
+    ...(operation.selectionPath === undefined ? {} : { selectionPath: operation.selectionPath }),
+  };
+}
+
+function toMetadataRecord(value: DataContractValue | undefined): DataContractRecord {
+  return isDataContractRecord(value) ? { ...value } : {};
+}
+
+function isDataContractRecord(value: DataContractValue | undefined): value is DataContractRecord {
+  return (
+    value !== undefined && typeof value === 'object' && value !== null && !Array.isArray(value)
+  );
+}