feat(sql): add index-type registry primitive

packages/1-framework/2-authoring/contract/src/descriptors.ts

@@ -8,8 +8,8 @@ export type ColumnTypeDescriptor<TCodecId extends string = string> = {
 export interface IndexDef {
   readonly columns: readonly string[];
   readonly name?: string;
-  readonly using?: string;
-  readonly config?: Record<string, unknown>;
+  readonly type?: string;
+  readonly options?: Record<string, unknown>;
 }
 
 export interface ForeignKeyDefaultsState {

packages/1-framework/2-authoring/contract/test/descriptors.test.ts

@@ -30,15 +30,15 @@ describe('descriptor exports', () => {
     const index: IndexDef = {
       columns: ['email'],
       name: 'user_email_idx',
-      using: 'btree',
-      config: { fillfactor: 90 },
+      type: 'btree',
+      options: { fillfactor: 90 },
     };
 
     expect(index).toEqual({
       columns: ['email'],
       name: 'user_email_idx',
-      using: 'btree',
-      config: { fillfactor: 90 },
+      type: 'btree',
+      options: { fillfactor: 90 },
     });
   });
 });

packages/2-sql/1-core/contract/package.json

@@ -33,6 +33,8 @@
   ],
   "exports": {
     "./factories": "./dist/factories.mjs",
+    "./index-type-validation": "./dist/index-type-validation.mjs",
+    "./index-types": "./dist/index-types.mjs",
     "./pack-types": "./dist/pack-types.mjs",
     "./types": "./dist/types.mjs",
     "./validate": "./dist/validate.mjs",

packages/2-sql/1-core/contract/src/exports/index-type-validation.ts

@@ -0,0 +1 @@
+export * from '../index-type-validation';

packages/2-sql/1-core/contract/src/exports/index-types.ts

@@ -0,0 +1,9 @@
+export {
+  createIndexTypeRegistry,
+  defineIndexTypes,
+  type IndexTypeBuilder,
+  type IndexTypeEntry,
+  type IndexTypeMap,
+  type IndexTypeRegistration,
+  type IndexTypeRegistry,
+} from '../index-types';

packages/2-sql/1-core/contract/src/index-type-validation.ts

@@ -0,0 +1,37 @@
+import type { Contract } from '@prisma-next/contract/types';
+import { ContractValidationError } from '@prisma-next/contract/validate-contract';
+import { type } from 'arktype';
+import type { IndexTypeRegistry } from './index-types';
+import type { SqlStorage } from './types';
+
+export function validateIndexTypes(
+  contract: Contract<SqlStorage>,
+  indexTypeRegistry: IndexTypeRegistry,
+): void {
+  for (const [tableName, table] of Object.entries(contract.storage.tables)) {
+    for (const index of table.indexes) {
+      if (index.type === undefined && index.options !== undefined) {
+        throw new ContractValidationError(
+          `Table "${tableName}" index on columns [${index.columns.join(', ')}] has options without a type`,
+          'storage',
+        );
+      }
+      if (index.type === undefined) continue;
+      const entry = indexTypeRegistry.get(index.type);
+      if (entry === undefined) {
+        throw new ContractValidationError(
+          `Table "${tableName}" index on columns [${index.columns.join(', ')}] uses unregistered index type "${index.type}"`,
+          'storage',
+        );
+      }
+      const optionsValue = index.options ?? {};
+      const result = entry.options(optionsValue);
+      if (result instanceof type.errors) {
+        throw new ContractValidationError(
+          `Table "${tableName}" index on columns [${index.columns.join(', ')}] has invalid options for type "${index.type}": ${result.summary}`,
+          'storage',
+        );
+      }
+    }
+  }
+}

packages/2-sql/1-core/contract/src/index-types.ts

@@ -0,0 +1,77 @@
+import type { Type } from 'arktype';
+
+export interface IndexTypeEntry<TOptions = unknown> {
+  readonly type: string;
+  readonly options: Type<TOptions>;
+}
+
+export type IndexTypeMap = { readonly [K in string]: { readonly options: unknown } };
+
+export interface IndexTypeRegistration<TMap extends IndexTypeMap = Record<never, never>> {
+  readonly IndexTypes: TMap;
+  readonly entries: ReadonlyArray<IndexTypeEntry>;
+}
+
+export interface IndexTypeBuilder<TMap extends IndexTypeMap = Record<never, never>>
+  extends IndexTypeRegistration<TMap> {
+  add<TLit extends string, TOpts>(
+    typeLiteral: TLit,
+    entry: { readonly options: Type<TOpts> },
+  ): IndexTypeBuilder<TMap & Record<TLit, { readonly options: TOpts }>>;
+}
+
+class IndexTypeBuilderImpl<TMap extends IndexTypeMap> implements IndexTypeBuilder<TMap> {
+  readonly entries: ReadonlyArray<IndexTypeEntry>;
+  readonly IndexTypes: TMap;
+
+  constructor(entries: ReadonlyArray<IndexTypeEntry>) {
+    this.entries = entries;
+    this.IndexTypes = {} as TMap;
+  }
+
+  add<TLit extends string, TOpts>(
+    typeLiteral: TLit,
+    entry: { readonly options: Type<TOpts> },
+  ): IndexTypeBuilder<TMap & Record<TLit, { readonly options: TOpts }>> {
+    if (this.entries.some((e) => e.type === typeLiteral)) {
+      throw new Error(`Index type "${typeLiteral}" is already declared in this builder`);
+    }
+    return new IndexTypeBuilderImpl<TMap & Record<TLit, { readonly options: TOpts }>>([
+      ...this.entries,
+      { type: typeLiteral, options: entry.options as Type<unknown> },
+    ]);
+  }
+}
+
+export function defineIndexTypes(): IndexTypeBuilder<Record<never, never>> {
+  return new IndexTypeBuilderImpl([]);
+}
+
+export interface IndexTypeRegistry {
+  register(entry: IndexTypeEntry): void;
+  get(typeLiteral: string): IndexTypeEntry | undefined;
+  has(typeLiteral: string): boolean;
+}
+
+class IndexTypeRegistryImpl implements IndexTypeRegistry {
+  private readonly entries = new Map<string, IndexTypeEntry>();
+
+  register(entry: IndexTypeEntry): void {
+    if (this.entries.has(entry.type)) {
+      throw new Error(`Index type "${entry.type}" is already registered`);
+    }
+    this.entries.set(entry.type, entry);
+  }
+
+  get(typeLiteral: string): IndexTypeEntry | undefined {
+    return this.entries.get(typeLiteral);
+  }
+
+  has(typeLiteral: string): boolean {
+    return this.entries.has(typeLiteral);
+  }
+}
+
+export function createIndexTypeRegistry(): IndexTypeRegistry {
+  return new IndexTypeRegistryImpl();
+}

packages/2-sql/1-core/contract/src/index.ts

@@ -1,4 +1,6 @@
 export * from './exports/factories';
+export * from './exports/index-type-validation';
+export * from './exports/index-types';
 export * from './exports/types';
 export * from './exports/validate';
 export * from './exports/validators';

packages/2-sql/1-core/contract/src/types.ts

@@ -43,16 +43,8 @@ export type UniqueConstraint = {
 export type Index = {
   readonly columns: readonly string[];
   readonly name?: string;
-  /**
-   * Optional access method identifier.
-   * Extension-specific methods are represented as strings and interpreted
-   * by the owning extension package.
-   */
-  readonly using?: string;
-  /**
-   * Optional extension-owned index configuration payload.
-   */
-  readonly config?: Record<string, unknown>;
+  readonly type?: string;
+  readonly options?: Record<string, unknown>;
 };
 
 export type ForeignKeyReferences = {

packages/2-sql/1-core/contract/src/validators.ts

@@ -96,8 +96,8 @@ const UniqueConstraintSchema = type.declare<UniqueConstraint>().type({
 export const IndexSchema = type({
   columns: type.string.array().readonly(),
   'name?': 'string',
-  'using?': 'string',
-  'config?': 'Record<string, unknown>',
+  'type?': 'string',
+  'options?': 'Record<string, unknown>',
 });
 
 export const ForeignKeyReferencesSchema = type.declare<ForeignKeyReferences>().type({
@@ -375,6 +375,9 @@ export function validateStorageSemantics(storage: SqlStorage): string[] {
       seenUniqueDefinitions.add(signature);
     }
 
+    const sortOptions = (o: Record<string, unknown> | undefined): Record<string, unknown> | null =>
+      o ? Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b))) : null;
+
     const seenIndexDefinitions = new Set<string>();
     for (const index of table.indexes) {
       const duplicateColumn = findDuplicateValue(index.columns);
@@ -384,8 +387,8 @@ export function validateStorageSemantics(storage: SqlStorage): string[] {
 
       const signature = JSON.stringify({
         columns: index.columns,
-        using: index.using ?? null,
-        config: index.config ?? null,
+        type: index.type ?? null,
+        options: sortOptions(index.options),
       });
       if (seenIndexDefinitions.has(signature)) {
         errors.push(

packages/2-sql/1-core/contract/test/index-types.test.ts

@@ -0,0 +1,83 @@
+import { type } from 'arktype';
+import { describe, expect, it } from 'vitest';
+import { createIndexTypeRegistry, defineIndexTypes } from '../src/index-types';
+
+describe('defineIndexTypes builder', () => {
+  it('starts empty', () => {
+    const builder = defineIndexTypes();
+    expect(builder.entries).toEqual([]);
+  });
+
+  it('add() yields a new builder with the entry appended', () => {
+    const optionsValidator = type({ key_field: 'string' });
+    const builder = defineIndexTypes().add('bm25', { options: optionsValidator });
+    expect(builder.entries).toHaveLength(1);
+    expect(builder.entries[0]?.type).toBe('bm25');
+    expect(builder.entries[0]?.options).toBe(optionsValidator);
+  });
+
+  it('add() composes multiple distinct entries in order', () => {
+    const a = type({ a: 'string' });
+    const b = type({ b: 'string' });
+    const builder = defineIndexTypes().add('alpha', { options: a }).add('beta', { options: b });
+    expect(builder.entries.map((e) => e.type)).toEqual(['alpha', 'beta']);
+  });
+
+  it('add() does not mutate the prior builder', () => {
+    const opts = type({ x: 'string' });
+    const a = defineIndexTypes();
+    const b = a.add('alpha', { options: opts });
+    expect(a.entries).toEqual([]);
+    expect(b.entries).toHaveLength(1);
+  });
+
+  it('add() throws on duplicate type literal in the same builder', () => {
+    const opts = type({ x: 'string' });
+    const builder = defineIndexTypes().add('dup', { options: opts });
+    expect(() => builder.add('dup', { options: opts })).toThrow(/already declared/);
+  });
+});
+
+describe('createIndexTypeRegistry', () => {
+  it('register stores an entry; get returns it', () => {
+    const registry = createIndexTypeRegistry();
+    const entry = { type: 'demo', options: type({ fillfactor: 'number' }) };
+    registry.register(entry);
+    expect(registry.get('demo')).toBe(entry);
+  });
+
+  it('has reports presence', () => {
+    const registry = createIndexTypeRegistry();
+    expect(registry.has('absent')).toBe(false);
+    registry.register({ type: 'present', options: type({ k: 'string' }) });
+    expect(registry.has('present')).toBe(true);
+  });
+
+  it('get returns undefined for unknown types', () => {
+    const registry = createIndexTypeRegistry();
+    expect(registry.get('nonesuch')).toBeUndefined();
+  });
+
+  it('register throws on duplicate type', () => {
+    const registry = createIndexTypeRegistry();
+    const opts = type({ key: 'string' });
+    registry.register({ type: 'gin', options: opts });
+    expect(() => registry.register({ type: 'gin', options: opts })).toThrow(/already registered/);
+  });
+
+  it('error message names the offending type', () => {
+    const registry = createIndexTypeRegistry();
+    registry.register({ type: 'gist', options: type({ k: 'string' }) });
+    expect(() => registry.register({ type: 'gist', options: type({ k: 'string' }) })).toThrow(
+      /gist/,
+    );
+  });
+
+  it('two registries are independent', () => {
+    const a = createIndexTypeRegistry();
+    const b = createIndexTypeRegistry();
+    a.register({ type: 'shared', options: type({ k: 'string' }) });
+    expect(a.has('shared')).toBe(true);
+    expect(b.has('shared')).toBe(false);
+  });
+});