@ankhorage/data-sources 1.0.1 → 2.0.1

package/src/generated-api/index.test.ts

@@ -1,173 +0,0 @@
-import type { GeneratedApiDefinition } from '@ankhorage/contracts/data';
-import { describe, expect, it } from 'bun:test';
-
-import {
-  createGeneratedApiDataSource,
-  createGeneratedApiOperationId,
-  createGeneratedApiResourceSchema,
-  normalizeGeneratedApiDataSource,
-} from './index';
-
-function assertSerializable<TValue>(value: TValue): void {
-  expect(JSON.parse(JSON.stringify(value))).toEqual(value);
-}
-
-function createPostsApiDefinition(): GeneratedApiDefinition {
-  return {
-    id: 'posts-api',
-    protocol: 'rest',
-    name: 'Posts API',
-    basePath: '/api',
-    database: {
-      id: 'primary-db',
-      kind: 'database',
-      packageName: '@ankhorage/supabase-db',
-    },
-    resources: [
-      {
-        id: 'posts',
-        name: 'Posts',
-        path: '/posts',
-        operations: ['list', 'read', 'create', 'update', 'delete'],
-        collection: {
-          name: 'posts',
-          schema: 'public',
-          primaryKey: 'id',
-          fields: [
-            { name: 'id', type: 'uuid', required: true, unique: true },
-            { name: 'title', type: 'text', required: true },
-            { name: 'published', type: 'boolean', defaultValue: false },
-            { name: 'createdAt', type: 'datetime' },
-            { name: 'metadata', type: 'json' },
-          ],
-        },
-        seed: [{ id: 'seed-1', title: 'Hello' }],
-        policies: [{ id: 'posts-policy' }],
-      },
-    ],
-  };
-}
-
-describe('generated API normalization', () => {
-  it('generates deterministic operation IDs', () => {
-    expect(createGeneratedApiOperationId('posts', 'list')).toBe('posts.list');
-    expect(createGeneratedApiOperationId('posts', 'delete')).toBe('posts.delete');
-  });
-
-  it('generates a serializable resource schema from a DB collection', () => {
-    const [resource] = createPostsApiDefinition().resources;
-    expect(resource).toBeDefined();
-    if (resource === undefined) return;
-
-    const schema = createGeneratedApiResourceSchema(resource.collection);
-    assertSerializable(schema);
-    expect(schema.type).toBe('object');
-    expect(schema.properties?.id?.format).toBe('uuid');
-    expect(schema.properties?.createdAt?.format).toBe('date-time');
-    expect(schema.properties?.metadata?.type).toBe('object');
-    expect(schema.required).toEqual(['id', 'title']);
-  });
-
-  it('normalizes generated REST desired state into canonical API operations', () => {
-    const source = normalizeGeneratedApiDataSource(createPostsApiDefinition());
-
-    assertSerializable(source);
-    expect(source.kind).toBe('api');
-    expect(source.origin).toBe('generated');
-    expect(source.protocol).toBe('rest');
-    expect(source.generatedApiId).toBe('posts-api');
-    expect(source.adapter.id).toBe('primary-db');
-    expect(source.endpoints.posts?.kind).toBe('database');
-    expect(source.endpoints.posts?.path).toBe('/posts');
-    expect(source.endpoints.posts?.operations['posts.list']?.intent).toBe('read');
-    expect(source.endpoints.posts?.operations['posts.create']?.intent).toBe('create');
-    expect(source.endpoints.posts?.operations['posts.update']?.intent).toBe('update');
-    expect(source.endpoints.posts?.operations['posts.delete']?.intent).toBe('delete');
-    expect(source.endpoints.posts?.operations['posts.read']?.request?.parameters?.[0]?.name).toBe(
-      'id',
-    );
-  });
-
-  it('creates a diagnostic result for valid generated APIs', () => {
-    const result = createGeneratedApiDataSource(createPostsApiDefinition());
-
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.data.endpoints.posts?.operations['posts.list']).toBeDefined();
-      expect(result.diagnostics).toEqual([]);
-    }
-  });
-
-  it('supports multiple generated APIs backed by different database adapters', () => {
-    const postsApi = normalizeGeneratedApiDataSource(createPostsApiDefinition());
-    const analyticsApi = normalizeGeneratedApiDataSource({
-      id: 'analytics-api',
-      protocol: 'rest',
-      basePath: '/analytics',
-      database: {
-        id: 'analytics-db',
-        kind: 'database',
-        packageName: '@ankhorage/postgres-db',
-      },
-      resources: [
-        {
-          id: 'events',
-          path: '/events',
-          operations: ['list'],
-          collection: {
-            name: 'events',
-            primaryKey: 'id',
-            fields: [
-              { name: 'id', type: 'uuid', required: true, unique: true },
-              { name: 'name', type: 'text', required: true },
-            ],
-          },
-        },
-      ],
-    });
-
-    assertSerializable([postsApi, analyticsApi]);
-    expect(postsApi.adapter.id).toBe('primary-db');
-    expect(analyticsApi.adapter.id).toBe('analytics-db');
-    expect(analyticsApi.endpoints.events?.operations['events.list']?.intent).toBe('read');
-    expect(analyticsApi.endpoints.events?.operations['events.read']).toBeUndefined();
-  });
-
-  it('reports missing resources, invalid paths and missing primary keys', () => {
-    const emptyResult = createGeneratedApiDataSource({
-      id: 'empty-api',
-      protocol: 'rest',
-      basePath: 'api',
-      database: { id: 'db', kind: 'database' },
-      resources: [],
-    });
-    const missingPrimaryKeyResult = createGeneratedApiDataSource({
-      id: 'broken-api',
-      protocol: 'rest',
-      basePath: '/api',
-      database: { id: 'db', kind: 'database' },
-      resources: [
-        {
-          id: 'posts',
-          path: 'posts',
-          operations: ['read'],
-          collection: {
-            name: 'posts',
-            fields: [{ name: 'title', type: 'text' }],
-          },
-        },
-      ],
-    });
-
-    expect(emptyResult.ok).toBe(false);
-    expect(missingPrimaryKeyResult.ok).toBe(false);
-    if (!missingPrimaryKeyResult.ok) {
-      expect(missingPrimaryKeyResult.diagnostics.map((diagnostic) => diagnostic.path)).toContain(
-        'resources.posts.collection.primaryKey',
-      );
-      expect(missingPrimaryKeyResult.diagnostics.map((diagnostic) => diagnostic.path)).toContain(
-        'resources.posts.path',
-      );
-    }
-  });
-});

package/src/generated-api/index.ts

@@ -1,414 +0,0 @@
-import type {
-  DataContractValue,
-  DataEndpointConfig,
-  DataOperationConfig,
-  DataOperationIntent,
-  DataOperationParameter,
-  DataSchema,
-  DataSourceDiagnostic,
-  DataSourceDiagnosticResult,
-  GeneratedApiAuthRequirement,
-  GeneratedApiCrudOperation,
-  GeneratedApiDefinition,
-  GeneratedApiOperationPolicyRef,
-  GeneratedApiResourceDefinition,
-  GeneratedRestApiDataSourceConfig,
-  OperationId,
-} from '@ankhorage/contracts/data';
-import type {
-  DbCollectionDefinition,
-  DbFieldDefinition,
-  DbFieldType,
-} from '@ankhorage/contracts/db';
-
-import { validateGeneratedApiCollection } from './validateGeneratedApiCollection';
-
-export function createGeneratedApiDataSource(
-  definition: GeneratedApiDefinition,
-): DataSourceDiagnosticResult<GeneratedRestApiDataSourceConfig> {
-  const diagnostics = validateGeneratedApiDefinition(definition);
-  if (diagnostics.some((diagnostic) => diagnostic.severity === 'error')) {
-    return { ok: false, diagnostics };
-  }
-
-  return {
-    ok: true,
-    data: normalizeGeneratedApiDataSource(definition),
-    diagnostics,
-  };
-}
-
-export function validateGeneratedApiDefinition(
-  definition: GeneratedApiDefinition,
-): readonly DataSourceDiagnostic[] {
-  const diagnostics: DataSourceDiagnostic[] = [];
-  const resourceIds = new Set<string>();
-
-  if (definition.basePath.trim().length === 0 || !definition.basePath.startsWith('/')) {
-    diagnostics.push({
-      code: 'invalid-config',
-      dataSourceId: definition.id,
-      message: 'Generated API basePath must be a non-empty absolute path.',
-      path: 'basePath',
-      severity: 'error',
-    });
-  }
-
-  if (definition.resources.length === 0) {
-    diagnostics.push({
-      code: 'invalid-config',
-      dataSourceId: definition.id,
-      message: 'Generated API requires at least one resource.',
-      path: 'resources',
-      severity: 'error',
-    });
-  }
-
-  for (const resource of definition.resources) {
-    validateGeneratedApiResource(definition, resource, resourceIds, diagnostics);
-  }
-
-  return diagnostics;
-}
-
-export function normalizeGeneratedApiDataSource(
-  definition: GeneratedApiDefinition,
-): GeneratedRestApiDataSourceConfig {
-  const endpoints: Record<string, DataEndpointConfig> = {};
-  const schemas: Record<string, DataSchema> = {};
-
-  for (const resource of definition.resources) {
-    endpoints[resource.id] = createGeneratedApiEndpoint(definition, resource);
-    schemas[resource.id] = createGeneratedApiResourceSchema(resource.collection);
-  }
-
-  return {
-    id: definition.id,
-    kind: 'api',
-    origin: 'generated',
-    protocol: 'rest',
-    generatedApiId: definition.id,
-    name: definition.name,
-    description: definition.description,
-    adapter: definition.database,
-    endpoints,
-    schemas,
-    metadata: createGeneratedApiSourceMetadata(definition),
-  };
-}
-
-export function createGeneratedApiEndpoint(
-  definition: GeneratedApiDefinition,
-  resource: GeneratedApiResourceDefinition,
-): DataEndpointConfig {
-  const operations: Record<OperationId, DataOperationConfig> = {};
-
-  for (const operation of resource.operations) {
-    const config = createGeneratedApiOperation(definition, resource, operation);
-    operations[config.id] = config;
-  }
-
-  return {
-    id: resource.id,
-    kind: 'database',
-    name: resource.name,
-    description: resource.description,
-    path: resource.path,
-    operations,
-    metadata: createGeneratedApiResourceMetadata(definition, resource),
-  };
-}
-
-export function createGeneratedApiOperation(
-  definition: GeneratedApiDefinition,
-  resource: GeneratedApiResourceDefinition,
-  operation: GeneratedApiCrudOperation,
-): DataOperationConfig {
-  const operationId = createGeneratedApiOperationId(resource.id, operation);
-  const primaryKey = resolveGeneratedApiPrimaryKey(resource.collection);
-  const primaryKeyParameter =
-    primaryKey === undefined ? undefined : createPrimaryKeyParameter(primaryKey);
-
-  return {
-    id: operationId,
-    endpointId: resource.id,
-    name: createGeneratedApiOperationName(resource, operation),
-    protocol: 'database',
-    intent: mapGeneratedApiOperationIntent(operation),
-    path: resource.path,
-    request: createGeneratedApiOperationRequest(
-      resource.collection,
-      operation,
-      primaryKeyParameter,
-    ),
-    response: createGeneratedApiOperationResponse(resource.collection, operation),
-    metadata: createGeneratedApiOperationMetadata(definition, resource, operation),
-  };
-}
-
-export function createGeneratedApiOperationId(
-  resourceId: string,
-  operation: GeneratedApiCrudOperation,
-): OperationId {
-  return `${resourceId}.${operation}`;
-}
-
-export function createGeneratedApiResourceSchema(collection: DbCollectionDefinition): DataSchema {
-  const properties: Record<string, DataSchema> = {};
-  const required: string[] = [];
-
-  for (const field of collection.fields) {
-    properties[field.name] = createGeneratedApiFieldSchema(field);
-    if (field.required === true) required.push(field.name);
-  }
-
-  return {
-    type: 'object',
-    title: collection.name,
-    required: required.length > 0 ? required : undefined,
-    properties,
-  };
-}
-
-function validateGeneratedApiResource(
-  definition: GeneratedApiDefinition,
-  resource: GeneratedApiResourceDefinition,
-  resourceIds: Set<string>,
-  diagnostics: DataSourceDiagnostic[],
-): void {
-  if (resource.id.trim().length === 0) {
-    diagnostics.push(
-      resourceDiagnostic(definition, resource, 'Resource IDs must be non-empty.', 'id'),
-    );
-  } else if (resourceIds.has(resource.id)) {
-    diagnostics.push(
-      resourceDiagnostic(definition, resource, `Resource ID '${resource.id}' is duplicated.`, 'id'),
-    );
-  }
-  resourceIds.add(resource.id);
-
-  if (!resource.path.startsWith('/')) {
-    diagnostics.push(
-      resourceDiagnostic(
-        definition,
-        resource,
-        'Generated API resource paths must start with `/`.',
-        'path',
-      ),
-    );
-  }
-
-  if (resource.collection.name.trim().length === 0) {
-    diagnostics.push(
-      resourceDiagnostic(
-        definition,
-        resource,
-        'Generated API resource collections must have a non-empty name.',
-        'collection.name',
-      ),
-    );
-  }
-
-  diagnostics.push(...validateGeneratedApiCollection(definition, resource));
-
-  if (resource.operations.length === 0) {
-    diagnostics.push(
-      resourceDiagnostic(
-        definition,
-        resource,
-        'Generated API resources require at least one operation.',
-        'operations',
-      ),
-    );
-  }
-
-  const primaryKey = resolveGeneratedApiPrimaryKey(resource.collection);
-  if (
-    primaryKey === undefined &&
-    resource.operations.some((operation) => operation !== 'list' && operation !== 'create')
-  ) {
-    diagnostics.push(
-      resourceDiagnostic(
-        definition,
-        resource,
-        'Generated API resources need a primaryKey field for read/update/delete operations.',
-        'collection.primaryKey',
-      ),
-    );
-  }
-}
-
-function resourceDiagnostic(
-  definition: GeneratedApiDefinition,
-  resource: GeneratedApiResourceDefinition,
-  message: string,
-  path: string,
-): DataSourceDiagnostic {
-  return {
-    code: 'invalid-config',
-    dataSourceId: definition.id,
-    endpointId: resource.id,
-    message,
-    path: `resources.${resource.id}.${path}`,
-    severity: 'error',
-  };
-}
-
-function createGeneratedApiSourceMetadata(definition: GeneratedApiDefinition): DataContractValue {
-  return {
-    ...readMetadataRecord(definition.metadata),
-    basePath: definition.basePath,
-    source: 'generated-api',
-    auth: createGeneratedApiAuthMetadata(definition.auth),
-  };
-}
-
-function createGeneratedApiResourceMetadata(
-  definition: GeneratedApiDefinition,
-  resource: GeneratedApiResourceDefinition,
-): DataContractValue {
-  return {
-    ...readMetadataRecord(resource.metadata),
-    adapterId: definition.database.id,
-    collection: resource.collection.name,
-    schema: resource.collection.schema ?? null,
-    source: 'generated-api',
-    seed: resource.seed ?? [],
-    policies: createGeneratedApiPolicyMetadata(resource.policies),
-  };
-}
-
-function createGeneratedApiOperationMetadata(
-  definition: GeneratedApiDefinition,
-  resource: GeneratedApiResourceDefinition,
-  operation: GeneratedApiCrudOperation,
-): DataContractValue {
-  return {
-    adapterId: definition.database.id,
-    collection: resource.collection.name,
-    operation,
-    schema: resource.collection.schema ?? null,
-    source: 'generated-api',
-    policies: createGeneratedApiPolicyMetadata(
-      resource.policies?.filter(
-        (policy) => policy.operation === undefined || policy.operation === operation,
-      ),
-    ),
-  };
-}
-
-function createGeneratedApiAuthMetadata(
-  auth: GeneratedApiAuthRequirement | undefined,
-): DataContractValue {
-  if (auth === undefined) return null;
-
-  const metadata: Record<string, DataContractValue> = {};
-  if (auth.required !== undefined) metadata.required = auth.required;
-  if (auth.roles !== undefined) metadata.roles = auth.roles;
-  if (auth.permissions !== undefined) metadata.permissions = auth.permissions;
-  if (auth.policy !== undefined) metadata.policy = auth.policy;
-  if (auth.metadata !== undefined) metadata.metadata = auth.metadata;
-  return metadata;
-}
-
-function createGeneratedApiPolicyMetadata(
-  policies: readonly GeneratedApiOperationPolicyRef[] | undefined,
-): readonly DataContractValue[] {
-  return (policies ?? []).map((policy) => {
-    const metadata: Record<string, DataContractValue> = { id: policy.id };
-    if (policy.operation !== undefined) metadata.operation = policy.operation;
-    return metadata;
-  });
-}
-
-function createGeneratedApiOperationName(
-  resource: GeneratedApiResourceDefinition,
-  operation: GeneratedApiCrudOperation,
-): string {
-  return `${operation} ${resource.name ?? resource.id}`;
-}
-
-function mapGeneratedApiOperationIntent(operation: GeneratedApiCrudOperation): DataOperationIntent {
-  if (operation === 'list' || operation === 'read') return 'read';
-  if (operation === 'create') return 'create';
-  if (operation === 'update') return 'update';
-  return 'delete';
-}
-
-function createGeneratedApiOperationRequest(
-  collection: DbCollectionDefinition,
-  operation: GeneratedApiCrudOperation,
-  primaryKeyParameter: DataOperationParameter | undefined,
-): DataOperationConfig['request'] {
-  if (operation === 'list') {
-    return {
-      parameters: [
-        { name: 'limit', location: 'query', schema: { type: 'integer' } },
-        { name: 'offset', location: 'query', schema: { type: 'integer' } },
-      ],
-    };
-  }
-
-  if (operation === 'read' || operation === 'delete') {
-    return primaryKeyParameter === undefined ? undefined : { parameters: [primaryKeyParameter] };
-  }
-
-  const parameters =
-    operation === 'update' && primaryKeyParameter !== undefined ? [primaryKeyParameter] : undefined;
-
-  return {
-    parameters,
-    schema: createGeneratedApiResourceSchema(collection),
-  };
-}
-
-function createGeneratedApiOperationResponse(
-  collection: DbCollectionDefinition,
-  operation: GeneratedApiCrudOperation,
-): DataOperationConfig['response'] {
-  const schema = createGeneratedApiResourceSchema(collection);
-
-  if (operation === 'list') return { schema: { type: 'array', items: schema } };
-  if (operation === 'delete') {
-    return { schema: { type: 'object', properties: { deleted: { type: 'boolean' } } } };
-  }
-  return { schema };
-}
-
-function createPrimaryKeyParameter(primaryKey: string): DataOperationParameter {
-  return {
-    name: primaryKey,
-    location: 'path',
-    required: true,
-    schema: { type: 'string' },
-  };
-}
-
-function resolveGeneratedApiPrimaryKey(collection: DbCollectionDefinition): string | undefined {
-  return collection.primaryKey ?? collection.fields.find((field) => field.unique === true)?.name;
-}
-
-function createGeneratedApiFieldSchema(field: DbFieldDefinition): DataSchema {
-  return {
-    ...mapDbFieldTypeToDataSchema(field.type),
-    default: field.defaultValue,
-  };
-}
-
-function mapDbFieldTypeToDataSchema(type: DbFieldType): DataSchema {
-  if (type === 'boolean') return { type: 'boolean' };
-  if (type === 'datetime') return { type: 'string', format: 'date-time' };
-  if (type === 'json') return { type: 'object' };
-  if (type === 'number') return { type: 'number' };
-  if (type === 'uuid') return { type: 'string', format: 'uuid' };
-  return { type: 'string' };
-}
-
-function readMetadataRecord(
-  value: DataContractValue | undefined,
-): Record<string, DataContractValue> {
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) return {};
-  const metadata: Record<string, DataContractValue> = {};
-  for (const [key, item] of Object.entries(value)) metadata[key] = item;
-  return metadata;
-}

package/src/generated-api/validateGeneratedApiCollection.test.ts

@@ -1,91 +0,0 @@
-import type { GeneratedApiDefinition } from '@ankhorage/contracts/data';
-import { describe, expect, it } from 'bun:test';
-
-import { validateGeneratedApiDefinition } from './index';
-
-function createDefinition(): GeneratedApiDefinition {
-  return {
-    id: 'posts-api',
-    protocol: 'rest',
-    basePath: '/api',
-    database: { id: 'primary-db', kind: 'database' },
-    resources: [
-      {
-        id: 'posts',
-        path: '/posts',
-        operations: ['list', 'read'],
-        collection: {
-          name: 'posts',
-          primaryKey: 'id',
-          fields: [
-            { name: 'id', type: 'uuid', required: true, unique: true },
-            { name: 'title', type: 'text' },
-          ],
-        },
-      },
-    ],
-  };
-}
-
-function diagnosticPaths(definition: GeneratedApiDefinition): readonly string[] {
-  return validateGeneratedApiDefinition(definition).map((diagnostic) => diagnostic.path ?? '');
-}
-
-describe('generated API collection validation', () => {
-  it('rejects resources without fields', () => {
-    const definition = createDefinition();
-    const [resource] = definition.resources;
-    if (!resource) throw new Error('Expected resource fixture.');
-
-    const paths = diagnosticPaths({
-      ...definition,
-      resources: [{ ...resource, collection: { ...resource.collection, fields: [] } }],
-    });
-
-    expect(paths).toContain('resources.posts.collection.fields');
-  });
-
-  it('rejects empty and duplicate field names', () => {
-    const definition = createDefinition();
-    const [resource] = definition.resources;
-    if (!resource) throw new Error('Expected resource fixture.');
-
-    const paths = diagnosticPaths({
-      ...definition,
-      resources: [
-        {
-          ...resource,
-          collection: {
-            ...resource.collection,
-            fields: [
-              { name: '', type: 'text' },
-              { name: 'title', type: 'text' },
-              { name: 'title', type: 'text' },
-            ],
-          },
-        },
-      ],
-    });
-
-    expect(paths).toContain('resources.posts.collection.fields.0.name');
-    expect(paths).toContain('resources.posts.collection.fields.2.name');
-  });
-
-  it('rejects primary keys that do not reference a field', () => {
-    const definition = createDefinition();
-    const [resource] = definition.resources;
-    if (!resource) throw new Error('Expected resource fixture.');
-
-    const paths = diagnosticPaths({
-      ...definition,
-      resources: [
-        {
-          ...resource,
-          collection: { ...resource.collection, primaryKey: 'missing' },
-        },
-      ],
-    });
-
-    expect(paths).toContain('resources.posts.collection.primaryKey');
-  });
-});