@ankhorage/data-sources 0.6.0 → 1.0.0

package/src/graphql/index.ts

@@ -9,7 +9,7 @@ import type {
   DataSchemaRegistry,
   DataSourceDiagnostic,
   DataSourceDiagnosticResult,
-  GraphQlDataSourceConfig,
+  ExternalGraphQlApiDataSourceConfig,
   OperationId,
 } from '@ankhorage/contracts/data';
 
@@ -46,7 +46,6 @@ export const GRAPHQL_INTROSPECTION_QUERY = `query AnkhorageGraphQlIntrospection
 }`;
 
 export type GraphQlOperationKind = 'mutation' | 'query' | 'subscription';
-
 type DataContractRecord = Record<string, DataContractValue>;
 
 export interface GraphQlIntrospectionTypeRef {
@@ -137,17 +136,16 @@ export function normalizeGraphQlOperationId(kind: GraphQlOperationKind, name: st
     .replace(/[^A-Za-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
     .toLowerCase();
-
   return normalizedName.length > 0 ? `${kind}.${normalizedName}` : `${kind}.operation`;
 }
 
 export function createGraphQlDataSource(
   definition: GraphQlDataSourceDefinition,
-): DataSourceDiagnosticResult<GraphQlDataSourceConfig> {
+): DataSourceDiagnosticResult<ExternalGraphQlApiDataSourceConfig> {
   const diagnostics = validateGraphQlDataSource(definition);
-  const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === 'error');
-
-  if (hasErrors) return { ok: false, diagnostics };
+  if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
+    return { ok: false, diagnostics };
+  }
 
   return {
     ok: true,
@@ -197,13 +195,12 @@ export function validateGraphQlDataSource(
 
 export function normalizeGraphQlDataSource(
   definition: GraphQlDataSourceDefinition,
-): GraphQlDataSourceConfig {
+): ExternalGraphQlApiDataSourceConfig {
   const schemas = normalizeGraphQlIntrospectionSchemas(definition.introspection);
-  const introspectionOperations = normalizeGraphQlIntrospectionOperations(definition.introspection);
-  const manualOperations = definition.operations ?? [];
+  const discovered = normalizeGraphQlIntrospectionOperations(definition.introspection);
   const operations: Record<OperationId, DataOperationConfig> = {};
 
-  for (const operation of [...introspectionOperations, ...manualOperations]) {
+  for (const operation of [...discovered, ...(definition.operations ?? [])]) {
     operations[operation.id] = normalizeGraphQlOperation(operation);
   }
 
@@ -213,21 +210,19 @@ export function normalizeGraphQlDataSource(
     baseUrl: definition.endpointUrl,
     credential: definition.credential,
     operations,
-    metadata: {
-      source: 'graphql',
-    },
+    metadata: { source: 'graphql' },
   };
 
   return {
     id: definition.id,
-    kind: 'graphql',
+    kind: 'api',
+    origin: 'external',
+    protocol: 'graphql',
     name: definition.name,
     description: definition.description,
     endpointUrl: definition.endpointUrl,
     credential: definition.credential,
-    endpoints: {
-      graphql: endpoint,
-    },
+    endpoints: { graphql: endpoint },
     schemas,
     introspection: {
       enabled: definition.introspectionEnabled ?? definition.introspection !== undefined,
@@ -244,12 +239,10 @@ export function normalizeGraphQlIntrospectionSchemas(
   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;
 }
 
@@ -261,11 +254,9 @@ export function normalizeGraphQlIntrospectionOperations(
 
   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;
 }
 
@@ -276,8 +267,8 @@ function appendRootOperations(
   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),
@@ -287,21 +278,14 @@ function appendRootOperations(
       variables: normalizeGraphQlVariablesSchema(field.args ?? []),
       response: normalizeGraphQlTypeRef(field.type),
       selectionPath: `$.data.${field.name}`,
-      metadata: {
-        rootType: rootTypeName,
-        source: 'introspection',
-      },
+      metadata: { rootType: rootTypeName, source: 'introspection' },
     });
   }
 }
 
 function normalizeGraphQlOperation(operation: GraphQlOperationDefinition): DataOperationConfig {
   const response: DataOperationResponse | undefined =
-    operation.response === undefined
-      ? undefined
-      : {
-          schema: operation.response,
-        };
+    operation.response === undefined ? undefined : { schema: operation.response };
 
   return {
     id: operation.id,
@@ -310,17 +294,14 @@ function normalizeGraphQlOperation(operation: GraphQlOperationDefinition): DataO
     description: operation.description,
     protocol: 'graphql',
     intent: mapGraphQlOperationKindToIntent(operation.kind),
-    request: {
-      schema: operation.variables,
-    },
+    request: { schema: operation.variables },
     response,
     metadata: createGraphQlOperationMetadata(operation),
   };
 }
 
 function mapGraphQlOperationKindToIntent(kind: GraphQlOperationKind): DataOperationIntent {
-  if (kind === 'query' || kind === 'subscription') return 'read';
-  return 'action';
+  return kind === 'query' || kind === 'subscription' ? 'read' : 'action';
 }
 
 function normalizeGraphQlVariablesSchema(
@@ -349,7 +330,6 @@ 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',
@@ -358,7 +338,6 @@ function normalizeGraphQlType(type: GraphQlIntrospectionType): DataSchema {
       enum: type.enumValues?.map((value) => value.name),
     };
   }
-
   if (type.kind === 'SCALAR') {
     return {
       ...normalizeGraphQlNamedScalar(type.name),
@@ -366,19 +345,14 @@ function normalizeGraphQlType(type: GraphQlIntrospectionType): DataSchema {
       description: type.description ?? undefined,
     };
   }
-
   if (type.kind === 'UNION') {
     return {
       title: type.name ?? undefined,
       description: type.description ?? undefined,
-      anyOf: type.possibleTypes?.map((possibleType) => normalizeGraphQlTypeRef(possibleType)),
+      anyOf: type.possibleTypes?.map(normalizeGraphQlTypeRef),
     };
   }
-
-  return {
-    title: type.name ?? undefined,
-    description: type.description ?? undefined,
-  };
+  return { title: type.name ?? undefined, description: type.description ?? undefined };
 }
 
 function normalizeGraphQlObjectType(type: GraphQlIntrospectionType): DataSchema {
@@ -387,14 +361,11 @@ function normalizeGraphQlObjectType(type: GraphQlIntrospectionType): DataSchema
   const required: string[] = [];
 
   for (const field of fields ?? []) {
-    const fieldType = 'type' in field ? field.type : undefined;
-    if (fieldType === undefined) continue;
-
+    const fieldType = field.type;
     properties[field.name] = {
       ...normalizeGraphQlTypeRef(fieldType),
       description: field.description ?? undefined,
     };
-
     if (isGraphQlNonNull(fieldType)) required.push(field.name);
   }
 
@@ -409,27 +380,13 @@ function normalizeGraphQlObjectType(type: GraphQlIntrospectionType): DataSchema
 
 function normalizeGraphQlTypeRef(type: GraphQlIntrospectionTypeRef): DataSchema {
   if (type.kind === 'NON_NULL' && type.ofType !== undefined && type.ofType !== null) {
-    return {
-      ...normalizeGraphQlTypeRef(type.ofType),
-      nullable: false,
-    };
+    return { ...normalizeGraphQlTypeRef(type.ofType), nullable: false };
   }
-
   if (type.kind === 'LIST' && type.ofType !== undefined && type.ofType !== null) {
-    return {
-      type: 'array',
-      items: normalizeGraphQlTypeRef(type.ofType),
-    };
+    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 } };
-  }
-
+  if (type.kind === 'SCALAR') return normalizeGraphQlNamedScalar(type.name);
+  if (type.name !== undefined && type.name !== null) return { ref: { id: type.name } };
   return {};
 }
 
@@ -438,11 +395,7 @@ function normalizeGraphQlNamedScalar(name: string | null | undefined): DataSchem
   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,
-  };
+  return { type: 'string', format: name ?? undefined };
 }
 
 function isGraphQlNonNull(type: GraphQlIntrospectionTypeRef): boolean {
@@ -456,27 +409,14 @@ function isNamedGraphQlType(type: GraphQlIntrospectionType): boolean {
 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;
-  }
-
+  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 {};
-
-  const metadata: DataContractRecord = {};
-  for (const [key, item] of Object.entries(value)) {
-    metadata[key] = item;
-  }
-
-  return metadata;
+  return { ...value };
 }
 
 function isDataContractRecord(value: DataContractValue | undefined): value is DataContractRecord {

package/src/index.test.ts

@@ -1,39 +1,46 @@
-import type { RestDataSourceConfig } from '@ankhorage/contracts/data';
+import type { ExternalRestApiDataSourceConfig } from '@ankhorage/contracts/data';
 import { describe, expect, it } from 'bun:test';
 
 import {
   DATA_SOURCES_PACKAGE_NAME,
   getDataSourceKind,
   getDataSourcesPackageInfo,
+  isSupportedApiOrigin,
+  isSupportedApiProtocol,
   isSupportedDataSourceKind,
-  SUPPORTED_DATA_SOURCE_KINDS,
 } from './index';
 
-describe('data-sources package baseline', () => {
-  it('exports package metadata', () => {
-    const info = getDataSourcesPackageInfo();
-
-    expect(info.packageName).toBe(DATA_SOURCES_PACKAGE_NAME);
-    expect(info.supportedKinds).toEqual(SUPPORTED_DATA_SOURCE_KINDS);
+describe('data-sources package model', () => {
+  it('exports orthogonal package capabilities', () => {
+    expect(getDataSourcesPackageInfo()).toEqual({
+      packageName: DATA_SOURCES_PACKAGE_NAME,
+      supportedKinds: ['api', 'database'],
+      supportedApiOrigins: ['external', 'generated'],
+      supportedApiProtocols: ['graphql', 'rest'],
+    });
   });
 
-  it('recognizes supported shared contract data-source kinds', () => {
-    expect(isSupportedDataSourceKind('rest')).toBe(true);
-    expect(isSupportedDataSourceKind('openapi')).toBe(true);
-    expect(isSupportedDataSourceKind('graphql')).toBe(true);
-    expect(isSupportedDataSourceKind('managed-api')).toBe(true);
+  it('recognizes only canonical source dimensions', () => {
+    expect(isSupportedDataSourceKind('api')).toBe(true);
     expect(isSupportedDataSourceKind('database')).toBe(true);
-    expect(isSupportedDataSourceKind('studio')).toBe(false);
+    expect(isSupportedDataSourceKind('managed-api')).toBe(false);
+    expect(isSupportedDataSourceKind('openapi')).toBe(false);
+    expect(isSupportedApiOrigin('external')).toBe(true);
+    expect(isSupportedApiOrigin('generated')).toBe(true);
+    expect(isSupportedApiProtocol('rest')).toBe(true);
+    expect(isSupportedApiProtocol('graphql')).toBe(true);
   });
 
-  it('consumes data-source contracts from @ankhorage/contracts', () => {
-    const source: RestDataSourceConfig = {
+  it('consumes canonical contracts from @ankhorage/contracts', () => {
+    const source: ExternalRestApiDataSourceConfig = {
       id: 'cms',
-      kind: 'rest',
+      kind: 'api',
+      origin: 'external',
+      protocol: 'rest',
       baseUrl: 'https://cms.example.com',
       endpoints: {},
     };
 
-    expect(getDataSourceKind(source)).toBe('rest');
+    expect(getDataSourceKind(source)).toBe('api');
   });
 });

package/src/index.ts

@@ -1,36 +1,57 @@
-import type { DataSourceConfig, DataSourceKind } from '@ankhorage/contracts/data';
+import type {
+  ApiOrigin,
+  ApiProtocol,
+  DataSourceConfig,
+  DataSourceKind,
+} from '@ankhorage/contracts/data';
 
 export * from './discovery';
+export * from './generated-api';
 export * from './graphql';
-export * from './managed-api';
 export * from './openapi';
 export * from './rest';
 export * from './test-runner';
 
 export const DATA_SOURCES_PACKAGE_NAME = '@ankhorage/data-sources' as const;
-
 export const SUPPORTED_DATA_SOURCE_KINDS = [
+  'api',
   'database',
+] as const satisfies readonly DataSourceKind[];
+export const SUPPORTED_API_ORIGINS = [
+  'external',
+  'generated',
+] as const satisfies readonly ApiOrigin[];
+export const SUPPORTED_API_PROTOCOLS = [
   'graphql',
-  'managed-api',
-  'openapi',
   'rest',
-] as const satisfies readonly DataSourceKind[];
+] as const satisfies readonly ApiProtocol[];
 
 export interface DataSourcesPackageInfo {
   readonly packageName: typeof DATA_SOURCES_PACKAGE_NAME;
   readonly supportedKinds: typeof SUPPORTED_DATA_SOURCE_KINDS;
+  readonly supportedApiOrigins: typeof SUPPORTED_API_ORIGINS;
+  readonly supportedApiProtocols: typeof SUPPORTED_API_PROTOCOLS;
 }
 
 export function getDataSourcesPackageInfo(): DataSourcesPackageInfo {
   return {
     packageName: DATA_SOURCES_PACKAGE_NAME,
     supportedKinds: SUPPORTED_DATA_SOURCE_KINDS,
+    supportedApiOrigins: SUPPORTED_API_ORIGINS,
+    supportedApiProtocols: SUPPORTED_API_PROTOCOLS,
   };
 }
 
 export function isSupportedDataSourceKind(kind: string): kind is DataSourceKind {
-  return SUPPORTED_DATA_SOURCE_KINDS.some((supportedKind) => supportedKind === kind);
+  return SUPPORTED_DATA_SOURCE_KINDS.some((supported) => supported === kind);
+}
+
+export function isSupportedApiOrigin(origin: string): origin is ApiOrigin {
+  return SUPPORTED_API_ORIGINS.some((supported) => supported === origin);
+}
+
+export function isSupportedApiProtocol(protocol: string): protocol is ApiProtocol {
+  return SUPPORTED_API_PROTOCOLS.some((supported) => supported === protocol);
 }
 
 export function getDataSourceKind(source: DataSourceConfig): DataSourceKind {