@prisma-next/extension-paradedb 0.5.0-dev.81 → 0.5.0-dev.82

package/README.md

@@ -4,21 +4,21 @@ ParadeDB full-text search extension pack for Prisma Next.
 
 ## Overview
 
-This extension pack adds support for [ParadeDB](https://docs.paradedb.com/) BM25 full-text search indexes in the contract authoring layer. It keeps BM25 metadata inside extension-owned index `config` payloads, so `contract.json` and `contract.d.ts` carry the full search schema without hard-coding ParadeDB types into core SQL index IR.
+This extension pack registers a `'bm25'` index type with the SQL family's index-type registry, so contracts can author BM25 full-text search indexes via the standard `constraints.index(...)` surface and the Postgres adapter emits `CREATE INDEX ... USING bm25 WITH (...)` DDL.
 
-This is the **contract-only foundation**. Query-plane support (`@@@` operator, `pdb.*` functions) and migration-plane support (`CREATE INDEX ... USING bm25` DDL generation) are planned as follow-up work.
+The v1 surface covers the `key_field` storage parameter only. Per-field tokenizer and column configuration is deferred to expression-index support.
 
 ## Responsibilities
 
-- **BM25 Index Authoring**: Typed `bm25.*` field builders for defining BM25 indexes in `contract.ts`
-- **Tokenizer Catalog**: `TokenizerId` type union covering all 12 built-in ParadeDB tokenizers
-- **Extension Descriptor**: Declares `paradedb/bm25` capability for contract-level feature detection
-- **Pack Ref Export**: Ships a pure `/pack` entrypoint for TypeScript contract authoring
+- **bm25 index registration**: declares a `'bm25'` entry via `defineIndexTypes()` carrying an arktype validator for the bm25 options shape
+- **Extension descriptor**: declares the `paradedb/bm25` capability for contract-level feature detection
+- **Pack ref export**: ships a pure `/pack` entrypoint for TypeScript contract authoring
 
 ## Dependencies
 
-- **`@prisma-next/contract`**: Core contract types
-- **`@prisma-next/contract-authoring`**: Column type descriptor interface
+- **`@prisma-next/sql-contract`**: index-type registry primitive
+- **`@prisma-next/contract`** / **`@prisma-next/contract-authoring`**: core contract types
+- **`arktype`**: option-shape validation
 
 ## Installation
 
@@ -28,15 +28,14 @@ pnpm add @prisma-next/extension-paradedb
 
 ## Usage
 
-### Contract Definition
+### Contract definition
 
-Define BM25 indexes on your tables using `bm25` field builders plus `bm25Index()`:
+Author bm25 indexes via the standard `constraints.index(...)` surface; the registered `'bm25'` entry narrows `options` per-`type`:
 
 ```typescript
-import { int4Column, textColumn, jsonbColumn } from '@prisma-next/adapter-postgres/column-types';
+import { int4Column, textColumn } from '@prisma-next/adapter-postgres/column-types';
 import sqlFamily from '@prisma-next/family-sql/pack';
 import { defineContract, field, model } from '@prisma-next/sql-contract-ts/contract-builder';
-import { bm25, bm25Index } from '@prisma-next/extension-paradedb/index-types';
 import paradedb from '@prisma-next/extension-paradedb/pack';
 import postgres from '@prisma-next/target-postgres/pack';
 
@@ -48,121 +47,40 @@ export const contract = defineContract({
     Item: model('Item', {
       fields: {
         id: field.column(int4Column).id(),
-        description: field.column(textColumn),
-        category: field.column(textColumn),
-        rating: field.column(int4Column),
-        metadata: field.column(jsonbColumn),
+        body: field.column(textColumn),
       },
-    }).sql({
+    }).sql(({ cols, constraints }) => ({
       table: 'items',
       indexes: [
-        bm25Index({
-          keyField: 'id',
-          fields: [
-            bm25.text('description', { tokenizer: 'simple', stemmer: 'english' }),
-            bm25.text('category'),
-            bm25.numeric('rating'),
-            bm25.json('metadata', { tokenizer: 'ngram', min: 2, max: 3 }),
-          ],
-          name: 'search_idx',
+        constraints.index([cols.body], {
+          name: 'item_body_bm25_idx',
+          type: 'bm25',
+          options: { key_field: 'id' },
         }),
       ],
-    }),
+    })),
   },
 });
 ```
 
-### Field Builders
+### key_field
 
-The `bm25` namespace provides typed field builders that produce `Bm25FieldConfig` objects:
-
-| Builder | Description | Tokenizer support |
-|---------|-------------|-------------------|
-| `bm25.text(column, opts?)` | Text field (`text`, `varchar`) | Yes — any tokenizer + stemmer, remove_emojis |
-| `bm25.numeric(column)` | Numeric field (filterable, sortable) | No |
-| `bm25.boolean(column)` | Boolean field | No |
-| `bm25.json(column, opts?)` | JSON/JSONB field | Yes — tokenizer + ngram params |
-| `bm25.datetime(column)` | Timestamp/date field | No |
-| `bm25.range(column)` | Range field | No |
-| `bm25.expression(sql, opts)` | Raw SQL expression | Yes — `alias` required |
-
-### Expression-Based Fields
-
-For computed or JSON sub-field indexing, use `bm25.expression()` with a raw SQL string:
-
-```typescript
-.index(
-  bm25Index({
-    keyField: 'id',
-    fields: [
-      bm25.text('description'),
-      bm25.expression("description || ' ' || category", {
-        alias: 'concat',
-        tokenizer: 'simple',
-      }),
-      bm25.expression("(metadata->>'color')", {
-        alias: 'meta_color',
-        tokenizer: 'ngram',
-        min: 2,
-        max: 3,
-      }),
-    ],
-  }),
-)
-```
-
-### keyField Behavior
-
-ParadeDB BM25 indexes require a `key_field` — a unique column that identifies each document:
-
-- **Required**: Set `keyField` explicitly in `bm25Index(...)`.
-- **Recommended**: Use the table primary key in most cases.
-- **Override**: You can choose another unique column when needed.
-
-```typescript
-.index(bm25Index({ keyField: 'id', fields: [bm25.text('body')] }))
-.index(bm25Index({ keyField: 'uuid', fields: [bm25.text('body')] }))
-```
-
-## Tokenizers
-
-All 12 built-in ParadeDB tokenizers are available via the `TokenizerId` type:
-
-| Tokenizer | Description |
-|-----------|-------------|
-| `unicode_words` | Default. Unicode word boundaries (UAX #29). Lowercases. |
-| `simple` | Splits on non-alphanumeric. Lowercases. |
-| `ngram` | Character n-grams of configurable length. |
-| `icu` | ICU Unicode standard segmentation. Multilingual. |
-| `regex_pattern` | Regex-based tokenization. |
-| `source_code` | camelCase / snake_case splitting. |
-| `literal` | No splitting. Exact match, sort, aggregation. |
-| `literal_normalized` | Literal + lowercase + token filters. |
-| `whitespace` | Whitespace splitting + lowercase. |
-| `chinese_compatible` | CJK-aware word segmentation. |
-| `jieba` | Chinese segmentation via Jieba. |
-| `lindera` | Japanese/Korean/Chinese via Lindera. |
+ParadeDB BM25 indexes require a `key_field` — a unique column that identifies each document. It is required, must be a string, and is typically (but not always) the table's primary key.
 
 ## Capabilities
 
-The extension declares:
-
-- `paradedb/bm25`: Indicates support for BM25 full-text search indexes
-
-## Not Yet Implemented
+- `paradedb/bm25` — indicates support for BM25 full-text search indexes
 
-The following are planned for follow-up work:
+## Not yet implemented
 
-- **Query plane**: `@@@` operator support in the sql-orm query builder
-- **Query plane**: `pdb.*` query builder functions (match, term, phrase, fuzzy, etc.)
-- **Migration plane**: `CREATE INDEX ... USING bm25` DDL generation from contract diffs
-- **Runtime**: Scoring, aggregation, and highlight functions
-- **Database dependencies**: `CREATE EXTENSION pg_search` via migration planner
+- Per-column / per-expression tokenizer configuration (deferred to expression-index support)
+- `@@@` operator and `pdb.*` query builder functions
+- `CREATE EXTENSION pg_search` via migration planner
+- Scoring, aggregation, and highlight functions
 
 ## References
 
 - [ParadeDB documentation](https://docs.paradedb.com/)
 - [ParadeDB CREATE INDEX](https://docs.paradedb.com/documentation/indexing/create-index)
-- [ParadeDB Tokenizers](https://docs.paradedb.com/documentation/tokenizers/overview)
-- [pg_search source](https://github.com/paradedb/paradedb/tree/main/pg_search)
+- [ADR 210 — Index-type registry](../../../docs/architecture%20docs/adrs/ADR%20210%20-%20Index-type%20registry.md)
 - [Prisma Next Architecture Overview](../../../docs/Architecture%20Overview.md)

package/dist/control.d.mts

@@ -1,3 +1,5 @@
+import * as _$_prisma_next_sql_contract_index_types0 from "@prisma-next/sql-contract/index-types";
+
 //#region src/core/descriptor-meta.d.ts
 declare const paradedbPackMeta: {
   readonly kind: "extension";
@@ -10,6 +12,11 @@ declare const paradedbPackMeta: {
       readonly 'paradedb/bm25': true;
     };
   };
+  readonly indexTypes: _$_prisma_next_sql_contract_index_types0.IndexTypeBuilder<Record<never, never> & Record<"bm25", {
+    readonly options: {
+      key_field: string;
+    };
+  }>>;
 };
 //#endregion
 export { paradedbPackMeta };

package/dist/control.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"control.d.mts","names":[],"sources":["../src/core/descriptor-meta.ts"],"mappings":";cAEa,gBAAA;EAAA"}
+{"version":3,"file":"control.d.mts","names":[],"sources":["../src/core/descriptor-meta.ts"],"mappings":";;;cAGa,gBAAA;EAAA"}

package/dist/control.mjs

@@ -1,2 +1,2 @@
-import { t as paradedbPackMeta } from "./descriptor-meta-B6-NIHhB.mjs";
+import { t as paradedbPackMeta } from "./descriptor-meta-BF_fQseQ.mjs";
 export { paradedbPackMeta };

package/dist/{descriptor-meta-B6-NIHhB.mjs → descriptor-meta-BF_fQseQ.mjs}

@@ -1,3 +1,4 @@
+import { t as paradedbIndexTypes } from "./index-types-BWFfNqUb.mjs";
 //#endregion
 //#region src/core/descriptor-meta.ts
 const paradedbPackMeta = {
@@ -6,9 +7,10 @@ const paradedbPackMeta = {
 	familyId: "sql",
 	targetId: "postgres",
 	version: "0.0.1",
-	capabilities: { postgres: { "paradedb/bm25": true } }
+	capabilities: { postgres: { "paradedb/bm25": true } },
+	indexTypes: paradedbIndexTypes
 };
 //#endregion
 export { paradedbPackMeta as t };
 
-//# sourceMappingURL=descriptor-meta-B6-NIHhB.mjs.map
+//# sourceMappingURL=descriptor-meta-BF_fQseQ.mjs.map

package/dist/descriptor-meta-BF_fQseQ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor-meta-BF_fQseQ.mjs","names":[],"sources":["../src/core/constants.ts","../src/core/descriptor-meta.ts"],"sourcesContent":["/**\n * Extension ID for ParadeDB pg_search.\n */\nexport const PARADEDB_EXTENSION_ID = 'paradedb' as const;\n","import { paradedbIndexTypes } from '../types/index-types';\nimport { PARADEDB_EXTENSION_ID } from './constants';\n\nexport const paradedbPackMeta = {\n  kind: 'extension',\n  id: PARADEDB_EXTENSION_ID,\n  familyId: 'sql',\n  targetId: 'postgres',\n  version: '0.0.1',\n  capabilities: {\n    postgres: {\n      'paradedb/bm25': true,\n    },\n  },\n  indexTypes: paradedbIndexTypes,\n} as const;\n"],"mappings":";;;ACGA,MAAa,mBAAmB;CAC9B,MAAM;CACN,IAAI;CACJ,UAAU;CACV,UAAU;CACV,SAAS;CACT,cAAc,EACZ,UAAU,EACR,iBAAiB,MAClB,EACF;CACD,YAAY;CACb"}

package/dist/index-types-BWFfNqUb.mjs

@@ -0,0 +1,11 @@
+import { defineIndexTypes } from "@prisma-next/sql-contract/index-types";
+import { type } from "arktype";
+//#region src/types/index-types.ts
+const paradedbIndexTypes = defineIndexTypes().add("bm25", { options: type({
+	"+": "reject",
+	key_field: "string"
+}) });
+//#endregion
+export { paradedbIndexTypes as t };
+
+//# sourceMappingURL=index-types-BWFfNqUb.mjs.map

package/dist/index-types-BWFfNqUb.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-types-BWFfNqUb.mjs","names":[],"sources":["../src/types/index-types.ts"],"sourcesContent":["import { defineIndexTypes } from '@prisma-next/sql-contract/index-types';\nimport { type } from 'arktype';\n\nexport const paradedbIndexTypes = defineIndexTypes().add('bm25', {\n  options: type({\n    '+': 'reject',\n    key_field: 'string',\n  }),\n});\n\nexport type IndexTypes = typeof paradedbIndexTypes.IndexTypes;\nexport type Bm25IndexOptions = IndexTypes['bm25']['options'];\n"],"mappings":";;;AAGA,MAAa,qBAAqB,kBAAkB,CAAC,IAAI,QAAQ,EAC/D,SAAS,KAAK;CACZ,KAAK;CACL,WAAW;CACZ,CAAC,EACH,CAAC"}

package/dist/index-types.d.mts

@@ -1,101 +1,13 @@
-import { IndexDef } from "@prisma-next/contract-authoring";
+import * as _$_prisma_next_sql_contract_index_types0 from "@prisma-next/sql-contract/index-types";
 
-//#region src/core/constants.d.ts
-/**
- * Built-in ParadeDB tokenizer IDs.
- * These correspond to the `pdb.*` casting syntax in `CREATE INDEX ... USING bm25`.
- */
-type TokenizerId = 'unicode_words' | 'simple' | 'ngram' | 'icu' | 'regex_pattern' | 'source_code' | 'literal' | 'literal_normalized' | 'whitespace' | 'chinese_compatible' | 'jieba' | 'lindera';
-//#endregion
 //#region src/types/index-types.d.ts
-/**
- * BM25 field config for a table column.
- */
-type Bm25ColumnFieldConfig = {
-  readonly column: string;
-  readonly expression?: never;
-  readonly tokenizer?: string;
-  readonly tokenizerParams?: Record<string, unknown>;
-  readonly alias?: string;
-};
-/**
- * BM25 field config for a SQL expression.
- */
-type Bm25ExpressionFieldConfig = {
-  readonly expression: string;
-  readonly column?: never;
-  readonly alias: string;
-  readonly tokenizer?: string;
-  readonly tokenizerParams?: Record<string, unknown>;
-};
-/**
- * BM25 field config union.
- */
-type Bm25FieldConfig = Bm25ColumnFieldConfig | Bm25ExpressionFieldConfig;
-/**
- * BM25 index configuration payload stored in `IndexDef.config`.
- */
-type Bm25IndexConfig = {
-  readonly keyField: string;
-  readonly fields: readonly Bm25FieldConfig[];
-};
-/**
- * Options for a BM25 text field (text, varchar columns).
- */
-type Bm25TextFieldOptions = {
-  readonly tokenizer?: TokenizerId | (string & {});
-  readonly stemmer?: string;
-  readonly alias?: string;
-  readonly remove_emojis?: boolean;
-};
-/**
- * Options for a BM25 JSON field (json, jsonb columns).
- */
-type Bm25JsonFieldOptions = {
-  readonly tokenizer?: TokenizerId | (string & {});
-  readonly alias?: string; /** Ngram-specific params when tokenizer is 'ngram'. */
-  readonly min?: number;
-  readonly max?: number;
-};
-/**
- * Options for a BM25 expression-based field.
- */
-type Bm25ExpressionFieldOptions = {
-  readonly alias: string;
-  readonly tokenizer?: TokenizerId | (string & {});
-  readonly min?: number;
-  readonly max?: number;
-  readonly stemmer?: string;
-  readonly pattern?: string;
-};
-/**
- * Options for constructing a BM25 index definition.
- */
-type Bm25IndexOptions = {
-  readonly keyField: string;
-  readonly fields: readonly Bm25FieldConfig[];
-  readonly name?: string;
-};
-/**
- * Typed BM25 field builders.
- * These produce `Bm25FieldConfig` objects for use in `bm25Index()`.
- */
-declare const bm25: {
-  /** Text field with optional tokenizer config. */readonly text: (column: string, opts?: Bm25TextFieldOptions) => Bm25FieldConfig; /** Numeric field (filterable, sortable in BM25). */
-  readonly numeric: (column: string) => Bm25FieldConfig; /** Boolean field. */
-  readonly boolean: (column: string) => Bm25FieldConfig; /** JSON/JSONB field with optional tokenizer config. */
-  readonly json: (column: string, opts?: Bm25JsonFieldOptions) => Bm25FieldConfig; /** Datetime (timestamp/date) field. */
-  readonly datetime: (column: string) => Bm25FieldConfig; /** Range field. */
-  readonly range: (column: string) => Bm25FieldConfig; /** Raw SQL expression field. `alias` is required. */
-  readonly expression: (sql: string, opts: Bm25ExpressionFieldOptions) => Bm25FieldConfig;
-};
-/**
- * Creates a generic index definition with a ParadeDB BM25 payload.
- *
- * `columns` only includes real table columns so core index validation remains
- * target-agnostic. Expression fields stay in extension-owned `config.fields`.
- */
-declare function bm25Index(opts: Bm25IndexOptions): IndexDef;
+declare const paradedbIndexTypes: _$_prisma_next_sql_contract_index_types0.IndexTypeBuilder<Record<never, never> & Record<"bm25", {
+  readonly options: {
+    key_field: string;
+  };
+}>>;
+type IndexTypes = typeof paradedbIndexTypes.IndexTypes;
+type Bm25IndexOptions = IndexTypes['bm25']['options'];
 //#endregion
-export { type Bm25ColumnFieldConfig, type Bm25ExpressionFieldConfig, type Bm25ExpressionFieldOptions, type Bm25FieldConfig, type Bm25IndexConfig, type Bm25IndexOptions, type Bm25JsonFieldOptions, type Bm25TextFieldOptions, type TokenizerId, bm25, bm25Index };
+export { type Bm25IndexOptions, type IndexTypes, paradedbIndexTypes };
 //# sourceMappingURL=index-types.d.mts.map

package/dist/index-types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index-types.d.mts","names":[],"sources":["../src/core/constants.ts","../src/types/index-types.ts"],"mappings":";;;;;;;KASY,WAAA;;;;AAAZ;;KCHY,qBAAA;EAAA,SACD,MAAA;EAAA,SACA,UAAA;EAAA,SACA,SAAA;EAAA,SACA,eAAA,GAAkB,MAAA;EAAA,SAClB,KAAA;AAAA;;;;KAMC,yBAAA;EAAA,SACD,UAAA;EAAA,SACA,MAAA;EAAA,SACA,KAAA;EAAA,SACA,SAAA;EAAA,SACA,eAAA,GAAkB,MAAA;AAAA;;AAL7B;;KAWY,eAAA,GAAkB,qBAAA,GAAwB,yBAAA;;;;KAK1C,eAAA;EAAA,SACD,QAAA;EAAA,SACA,MAAA,WAAiB,eAAA;AAAA;;;AAP5B;KAaY,oBAAA;EAAA,SACD,SAAA,GAAY,WAAA;EAAA,SACZ,OAAA;EAAA,SACA,KAAA;EAAA,SACA,aAAA;AAAA;;;;KAMC,oBAAA;EAAA,SACD,SAAA,GAAY,WAAA;EAAA,SACZ,KAAA,WAlBgC;EAAA,SAoBhC,GAAA;EAAA,SACA,GAAA;AAAA;;;;KAMC,0BAAA;EAAA,SACD,KAAA;EAAA,SACA,SAAA,GAAY,WAAA;EAAA,SACZ,GAAA;EAAA,SACA,GAAA;EAAA,SACA,OAAA;EAAA,SACA,OAAA;AAAA;;;;KAWC,gBAAA;EAAA,SACD,QAAA;EAAA,SACA,MAAA,WAAiB,eAAA;EAAA,SACjB,IAAA;AAAA;AApBX;;;;AAAA,cA2Ba,IAAA;EAzBF,iFA2BU,IAAA,GAAS,oBAAA,KAAuB,eAAA,EA1B1C;EAAA,sCAsCgB,eAAA,EApChB;EAAA,sCAyCgB,eAAA,EAxCT;EAAA,gCA6CG,IAAA,GAAS,oBAAA,KAAuB,eAAA,EAlCzC;EAAA,uCA2CgB,eAAA;sCAKH,eAAA,EA/Cd;EAAA,mCAoDa,IAAA,EAAQ,0BAAA,KAA6B,eAAA;AAAA;;;;AA3C7D;;;iBA+DgB,SAAA,CAAU,IAAA,EAAM,gBAAA,GAAmB,QAAA"}
+{"version":3,"file":"index-types.d.mts","names":[],"sources":["../src/types/index-types.ts"],"mappings":";;;cAGa,kBAAA,EAAkB,wCAAA,CAAA,gBAAA,CAAA,MAAA,iBAAA,MAAA;EAAA;;;;KAOnB,UAAA,UAAoB,kBAAA,CAAmB,UAAA;AAAA,KACvC,gBAAA,GAAmB,UAAA"}

package/dist/index-types.mjs

@@ -1,91 +1,2 @@
-//#region src/types/index-types.ts
-/**
-* Typed BM25 field builders.
-* These produce `Bm25FieldConfig` objects for use in `bm25Index()`.
-*/
-const bm25 = {
-	/** Text field with optional tokenizer config. */
-	text(column, opts) {
-		return {
-			column,
-			...buildTokenizerConfig(opts?.tokenizer, {
-				stemmer: opts?.stemmer,
-				remove_emojis: opts?.remove_emojis
-			}),
-			...opts?.alias !== void 0 && { alias: opts.alias }
-		};
-	},
-	/** Numeric field (filterable, sortable in BM25). */
-	numeric(column) {
-		return { column };
-	},
-	/** Boolean field. */
-	boolean(column) {
-		return { column };
-	},
-	/** JSON/JSONB field with optional tokenizer config. */
-	json(column, opts) {
-		return {
-			column,
-			...buildTokenizerConfig(opts?.tokenizer, {
-				min: opts?.min,
-				max: opts?.max
-			}),
-			...opts?.alias !== void 0 && { alias: opts.alias }
-		};
-	},
-	/** Datetime (timestamp/date) field. */
-	datetime(column) {
-		return { column };
-	},
-	/** Range field. */
-	range(column) {
-		return { column };
-	},
-	/** Raw SQL expression field. `alias` is required. */
-	expression(sql, opts) {
-		return {
-			expression: sql,
-			alias: opts.alias,
-			...buildTokenizerConfig(opts.tokenizer, {
-				min: opts.min,
-				max: opts.max,
-				stemmer: opts.stemmer,
-				pattern: opts.pattern
-			})
-		};
-	}
-};
-/**
-* Creates a generic index definition with a ParadeDB BM25 payload.
-*
-* `columns` only includes real table columns so core index validation remains
-* target-agnostic. Expression fields stay in extension-owned `config.fields`.
-*/
-function bm25Index(opts) {
-	return {
-		columns: opts.fields.flatMap((field) => "column" in field ? [field.column] : []),
-		...opts.name !== void 0 && { name: opts.name },
-		using: "bm25",
-		config: {
-			keyField: opts.keyField,
-			fields: opts.fields
-		}
-	};
-}
-/**
-* Builds `{ tokenizer, tokenizerParams? }` from a tokenizer ID and a bag of params.
-* Filters out undefined values and omits `tokenizerParams` when empty.
-*/
-function buildTokenizerConfig(tokenizer, params) {
-	if (!tokenizer) return {};
-	const filtered = Object.fromEntries(Object.entries(params).filter(([, v]) => v !== void 0));
-	return {
-		tokenizer,
-		...Object.keys(filtered).length > 0 && { tokenizerParams: filtered }
-	};
-}
-//#endregion
-export { bm25, bm25Index };
-
-//# sourceMappingURL=index-types.mjs.map
+import { t as paradedbIndexTypes } from "./index-types-BWFfNqUb.mjs";
+export { paradedbIndexTypes };

package/dist/pack.d.mts

@@ -1,3 +1,5 @@
+import * as _$_prisma_next_sql_contract_index_types0 from "@prisma-next/sql-contract/index-types";
+
 //#region src/exports/pack.d.ts
 declare const paradedbPack: {
   readonly kind: "extension";
@@ -10,6 +12,11 @@ declare const paradedbPack: {
       readonly 'paradedb/bm25': true;
     };
   };
+  readonly indexTypes: _$_prisma_next_sql_contract_index_types0.IndexTypeBuilder<Record<never, never> & Record<"bm25", {
+    readonly options: {
+      key_field: string;
+    };
+  }>>;
 };
 //#endregion
 export { paradedbPack as default };

package/dist/pack.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"pack.d.mts","names":[],"sources":["../src/exports/pack.ts"],"mappings":";cAEM,YAAA;EAAA"}
+{"version":3,"file":"pack.d.mts","names":[],"sources":["../src/exports/pack.ts"],"mappings":";;;cAEM,YAAA;EAAA"}

package/dist/pack.mjs

@@ -1,4 +1,4 @@
-import { t as paradedbPackMeta } from "./descriptor-meta-B6-NIHhB.mjs";
+import { t as paradedbPackMeta } from "./descriptor-meta-BF_fQseQ.mjs";
 //#region src/exports/pack.ts
 const paradedbPack = paradedbPackMeta;
 //#endregion

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "@prisma-next/extension-paradedb",
-  "version": "0.5.0-dev.81",
+  "version": "0.5.0-dev.82",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "dependencies": {
-    "@prisma-next/contract": "0.5.0-dev.81",
-    "@prisma-next/contract-authoring": "0.5.0-dev.81"
+    "arktype": "^2.1.25",
+    "@prisma-next/sql-contract": "0.5.0-dev.82",
+    "@prisma-next/contract-authoring": "0.5.0-dev.82",
+    "@prisma-next/contract": "0.5.0-dev.82"
   },
   "devDependencies": {
     "tsdown": "0.22.0",
     "typescript": "5.9.3",
     "vitest": "4.1.5",
-    "@prisma-next/tsdown": "0.0.0",
-    "@prisma-next/tsconfig": "0.0.0"
+    "@prisma-next/tsconfig": "0.0.0",
+    "@prisma-next/tsdown": "0.0.0"
   },
   "files": [
     "dist",

package/src/core/constants.ts

@@ -2,21 +2,3 @@
  * Extension ID for ParadeDB pg_search.
  */
 export const PARADEDB_EXTENSION_ID = 'paradedb' as const;
-
-/**
- * Built-in ParadeDB tokenizer IDs.
- * These correspond to the `pdb.*` casting syntax in `CREATE INDEX ... USING bm25`.
- */
-export type TokenizerId =
-  | 'unicode_words'
-  | 'simple'
-  | 'ngram'
-  | 'icu'
-  | 'regex_pattern'
-  | 'source_code'
-  | 'literal'
-  | 'literal_normalized'
-  | 'whitespace'
-  | 'chinese_compatible'
-  | 'jieba'
-  | 'lindera';

package/src/core/descriptor-meta.ts

@@ -1,3 +1,4 @@
+import { paradedbIndexTypes } from '../types/index-types';
 import { PARADEDB_EXTENSION_ID } from './constants';
 
 export const paradedbPackMeta = {
@@ -11,4 +12,5 @@ export const paradedbPackMeta = {
       'paradedb/bm25': true,
     },
   },
+  indexTypes: paradedbIndexTypes,
 } as const;

package/src/exports/index-types.ts

@@ -1,12 +1,2 @@
-export type { TokenizerId } from '../core/constants';
-export type {
-  Bm25ColumnFieldConfig,
-  Bm25ExpressionFieldConfig,
-  Bm25ExpressionFieldOptions,
-  Bm25FieldConfig,
-  Bm25IndexConfig,
-  Bm25IndexOptions,
-  Bm25JsonFieldOptions,
-  Bm25TextFieldOptions,
-} from '../types/index-types';
-export { bm25, bm25Index } from '../types/index-types';
+export type { Bm25IndexOptions, IndexTypes } from '../types/index-types';
+export { paradedbIndexTypes } from '../types/index-types';

package/src/types/index-types.ts

@@ -1,179 +1,12 @@
-import type { IndexDef } from '@prisma-next/contract-authoring';
-import type { TokenizerId } from '../core/constants';
-
-/**
- * BM25 field config for a table column.
- */
-export type Bm25ColumnFieldConfig = {
-  readonly column: string;
-  readonly expression?: never;
-  readonly tokenizer?: string;
-  readonly tokenizerParams?: Record<string, unknown>;
-  readonly alias?: string;
-};
-
-/**
- * BM25 field config for a SQL expression.
- */
-export type Bm25ExpressionFieldConfig = {
-  readonly expression: string;
-  readonly column?: never;
-  readonly alias: string;
-  readonly tokenizer?: string;
-  readonly tokenizerParams?: Record<string, unknown>;
-};
-
-/**
- * BM25 field config union.
- */
-export type Bm25FieldConfig = Bm25ColumnFieldConfig | Bm25ExpressionFieldConfig;
-
-/**
- * BM25 index configuration payload stored in `IndexDef.config`.
- */
-export type Bm25IndexConfig = {
-  readonly keyField: string;
-  readonly fields: readonly Bm25FieldConfig[];
-};
-
-/**
- * Options for a BM25 text field (text, varchar columns).
- */
-export type Bm25TextFieldOptions = {
-  readonly tokenizer?: TokenizerId | (string & {});
-  readonly stemmer?: string;
-  readonly alias?: string;
-  readonly remove_emojis?: boolean;
-};
-
-/**
- * Options for a BM25 JSON field (json, jsonb columns).
- */
-export type Bm25JsonFieldOptions = {
-  readonly tokenizer?: TokenizerId | (string & {});
-  readonly alias?: string;
-  /** Ngram-specific params when tokenizer is 'ngram'. */
-  readonly min?: number;
-  readonly max?: number;
-};
-
-/**
- * Options for a BM25 expression-based field.
- */
-export type Bm25ExpressionFieldOptions = {
-  readonly alias: string;
-  readonly tokenizer?: TokenizerId | (string & {});
-  readonly min?: number;
-  readonly max?: number;
-  readonly stemmer?: string;
-  readonly pattern?: string;
-};
-
-type TokenizerConfig = {
-  readonly tokenizer?: string;
-  readonly tokenizerParams?: Record<string, unknown>;
-};
-
-/**
- * Options for constructing a BM25 index definition.
- */
-export type Bm25IndexOptions = {
-  readonly keyField: string;
-  readonly fields: readonly Bm25FieldConfig[];
-  readonly name?: string;
-};
-
-/**
- * Typed BM25 field builders.
- * These produce `Bm25FieldConfig` objects for use in `bm25Index()`.
- */
-export const bm25 = {
-  /** Text field with optional tokenizer config. */
-  text(column: string, opts?: Bm25TextFieldOptions): Bm25FieldConfig {
-    return {
-      column,
-      ...buildTokenizerConfig(opts?.tokenizer, {
-        stemmer: opts?.stemmer,
-        remove_emojis: opts?.remove_emojis,
-      }),
-      ...(opts?.alias !== undefined && { alias: opts.alias }),
-    };
-  },
-
-  /** Numeric field (filterable, sortable in BM25). */
-  numeric(column: string): Bm25FieldConfig {
-    return { column };
-  },
-
-  /** Boolean field. */
-  boolean(column: string): Bm25FieldConfig {
-    return { column };
-  },
-
-  /** JSON/JSONB field with optional tokenizer config. */
-  json(column: string, opts?: Bm25JsonFieldOptions): Bm25FieldConfig {
-    return {
-      column,
-      ...buildTokenizerConfig(opts?.tokenizer, { min: opts?.min, max: opts?.max }),
-      ...(opts?.alias !== undefined && { alias: opts.alias }),
-    };
-  },
-
-  /** Datetime (timestamp/date) field. */
-  datetime(column: string): Bm25FieldConfig {
-    return { column };
-  },
-
-  /** Range field. */
-  range(column: string): Bm25FieldConfig {
-    return { column };
-  },
-
-  /** Raw SQL expression field. `alias` is required. */
-  expression(sql: string, opts: Bm25ExpressionFieldOptions): Bm25FieldConfig {
-    return {
-      expression: sql,
-      alias: opts.alias,
-      ...buildTokenizerConfig(opts.tokenizer, {
-        min: opts.min,
-        max: opts.max,
-        stemmer: opts.stemmer,
-        pattern: opts.pattern,
-      }),
-    };
-  },
-} as const;
-
-/**
- * Creates a generic index definition with a ParadeDB BM25 payload.
- *
- * `columns` only includes real table columns so core index validation remains
- * target-agnostic. Expression fields stay in extension-owned `config.fields`.
- */
-export function bm25Index(opts: Bm25IndexOptions): IndexDef {
-  return {
-    columns: opts.fields.flatMap((field) => ('column' in field ? [field.column] : [])),
-    ...(opts.name !== undefined && { name: opts.name }),
-    using: 'bm25',
-    config: {
-      keyField: opts.keyField,
-      fields: opts.fields,
-    } satisfies Bm25IndexConfig,
-  };
-}
-
-/**
- * Builds `{ tokenizer, tokenizerParams? }` from a tokenizer ID and a bag of params.
- * Filters out undefined values and omits `tokenizerParams` when empty.
- */
-function buildTokenizerConfig(
-  tokenizer: string | undefined,
-  params: Record<string, unknown>,
-): TokenizerConfig {
-  if (!tokenizer) return {};
-  const filtered = Object.fromEntries(Object.entries(params).filter(([, v]) => v !== undefined));
-  return {
-    tokenizer,
-    ...(Object.keys(filtered).length > 0 && { tokenizerParams: filtered }),
-  };
-}
+import { defineIndexTypes } from '@prisma-next/sql-contract/index-types';
+import { type } from 'arktype';
+
+export const paradedbIndexTypes = defineIndexTypes().add('bm25', {
+  options: type({
+    '+': 'reject',
+    key_field: 'string',
+  }),
+});
+
+export type IndexTypes = typeof paradedbIndexTypes.IndexTypes;
+export type Bm25IndexOptions = IndexTypes['bm25']['options'];

package/dist/descriptor-meta-B6-NIHhB.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"descriptor-meta-B6-NIHhB.mjs","names":[],"sources":["../src/core/constants.ts","../src/core/descriptor-meta.ts"],"sourcesContent":["/**\n * Extension ID for ParadeDB pg_search.\n */\nexport const PARADEDB_EXTENSION_ID = 'paradedb' as const;\n\n/**\n * Built-in ParadeDB tokenizer IDs.\n * These correspond to the `pdb.*` casting syntax in `CREATE INDEX ... USING bm25`.\n */\nexport type TokenizerId =\n  | 'unicode_words'\n  | 'simple'\n  | 'ngram'\n  | 'icu'\n  | 'regex_pattern'\n  | 'source_code'\n  | 'literal'\n  | 'literal_normalized'\n  | 'whitespace'\n  | 'chinese_compatible'\n  | 'jieba'\n  | 'lindera';\n","import { PARADEDB_EXTENSION_ID } from './constants';\n\nexport const paradedbPackMeta = {\n  kind: 'extension',\n  id: PARADEDB_EXTENSION_ID,\n  familyId: 'sql',\n  targetId: 'postgres',\n  version: '0.0.1',\n  capabilities: {\n    postgres: {\n      'paradedb/bm25': true,\n    },\n  },\n} as const;\n"],"mappings":";;ACEA,MAAa,mBAAmB;CAC9B,MAAM;CACN,IAAI;CACJ,UAAU;CACV,UAAU;CACV,SAAS;CACT,cAAc,EACZ,UAAU,EACR,iBAAiB,MAClB,EACF;CACF"}

package/dist/index-types.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index-types.mjs","names":[],"sources":["../src/types/index-types.ts"],"sourcesContent":["import type { IndexDef } from '@prisma-next/contract-authoring';\nimport type { TokenizerId } from '../core/constants';\n\n/**\n * BM25 field config for a table column.\n */\nexport type Bm25ColumnFieldConfig = {\n  readonly column: string;\n  readonly expression?: never;\n  readonly tokenizer?: string;\n  readonly tokenizerParams?: Record<string, unknown>;\n  readonly alias?: string;\n};\n\n/**\n * BM25 field config for a SQL expression.\n */\nexport type Bm25ExpressionFieldConfig = {\n  readonly expression: string;\n  readonly column?: never;\n  readonly alias: string;\n  readonly tokenizer?: string;\n  readonly tokenizerParams?: Record<string, unknown>;\n};\n\n/**\n * BM25 field config union.\n */\nexport type Bm25FieldConfig = Bm25ColumnFieldConfig | Bm25ExpressionFieldConfig;\n\n/**\n * BM25 index configuration payload stored in `IndexDef.config`.\n */\nexport type Bm25IndexConfig = {\n  readonly keyField: string;\n  readonly fields: readonly Bm25FieldConfig[];\n};\n\n/**\n * Options for a BM25 text field (text, varchar columns).\n */\nexport type Bm25TextFieldOptions = {\n  readonly tokenizer?: TokenizerId | (string & {});\n  readonly stemmer?: string;\n  readonly alias?: string;\n  readonly remove_emojis?: boolean;\n};\n\n/**\n * Options for a BM25 JSON field (json, jsonb columns).\n */\nexport type Bm25JsonFieldOptions = {\n  readonly tokenizer?: TokenizerId | (string & {});\n  readonly alias?: string;\n  /** Ngram-specific params when tokenizer is 'ngram'. */\n  readonly min?: number;\n  readonly max?: number;\n};\n\n/**\n * Options for a BM25 expression-based field.\n */\nexport type Bm25ExpressionFieldOptions = {\n  readonly alias: string;\n  readonly tokenizer?: TokenizerId | (string & {});\n  readonly min?: number;\n  readonly max?: number;\n  readonly stemmer?: string;\n  readonly pattern?: string;\n};\n\ntype TokenizerConfig = {\n  readonly tokenizer?: string;\n  readonly tokenizerParams?: Record<string, unknown>;\n};\n\n/**\n * Options for constructing a BM25 index definition.\n */\nexport type Bm25IndexOptions = {\n  readonly keyField: string;\n  readonly fields: readonly Bm25FieldConfig[];\n  readonly name?: string;\n};\n\n/**\n * Typed BM25 field builders.\n * These produce `Bm25FieldConfig` objects for use in `bm25Index()`.\n */\nexport const bm25 = {\n  /** Text field with optional tokenizer config. */\n  text(column: string, opts?: Bm25TextFieldOptions): Bm25FieldConfig {\n    return {\n      column,\n      ...buildTokenizerConfig(opts?.tokenizer, {\n        stemmer: opts?.stemmer,\n        remove_emojis: opts?.remove_emojis,\n      }),\n      ...(opts?.alias !== undefined && { alias: opts.alias }),\n    };\n  },\n\n  /** Numeric field (filterable, sortable in BM25). */\n  numeric(column: string): Bm25FieldConfig {\n    return { column };\n  },\n\n  /** Boolean field. */\n  boolean(column: string): Bm25FieldConfig {\n    return { column };\n  },\n\n  /** JSON/JSONB field with optional tokenizer config. */\n  json(column: string, opts?: Bm25JsonFieldOptions): Bm25FieldConfig {\n    return {\n      column,\n      ...buildTokenizerConfig(opts?.tokenizer, { min: opts?.min, max: opts?.max }),\n      ...(opts?.alias !== undefined && { alias: opts.alias }),\n    };\n  },\n\n  /** Datetime (timestamp/date) field. */\n  datetime(column: string): Bm25FieldConfig {\n    return { column };\n  },\n\n  /** Range field. */\n  range(column: string): Bm25FieldConfig {\n    return { column };\n  },\n\n  /** Raw SQL expression field. `alias` is required. */\n  expression(sql: string, opts: Bm25ExpressionFieldOptions): Bm25FieldConfig {\n    return {\n      expression: sql,\n      alias: opts.alias,\n      ...buildTokenizerConfig(opts.tokenizer, {\n        min: opts.min,\n        max: opts.max,\n        stemmer: opts.stemmer,\n        pattern: opts.pattern,\n      }),\n    };\n  },\n} as const;\n\n/**\n * Creates a generic index definition with a ParadeDB BM25 payload.\n *\n * `columns` only includes real table columns so core index validation remains\n * target-agnostic. Expression fields stay in extension-owned `config.fields`.\n */\nexport function bm25Index(opts: Bm25IndexOptions): IndexDef {\n  return {\n    columns: opts.fields.flatMap((field) => ('column' in field ? [field.column] : [])),\n    ...(opts.name !== undefined && { name: opts.name }),\n    using: 'bm25',\n    config: {\n      keyField: opts.keyField,\n      fields: opts.fields,\n    } satisfies Bm25IndexConfig,\n  };\n}\n\n/**\n * Builds `{ tokenizer, tokenizerParams? }` from a tokenizer ID and a bag of params.\n * Filters out undefined values and omits `tokenizerParams` when empty.\n */\nfunction buildTokenizerConfig(\n  tokenizer: string | undefined,\n  params: Record<string, unknown>,\n): TokenizerConfig {\n  if (!tokenizer) return {};\n  const filtered = Object.fromEntries(Object.entries(params).filter(([, v]) => v !== undefined));\n  return {\n    tokenizer,\n    ...(Object.keys(filtered).length > 0 && { tokenizerParams: filtered }),\n  };\n}\n"],"mappings":";;;;;AAyFA,MAAa,OAAO;;CAElB,KAAK,QAAgB,MAA8C;EACjE,OAAO;GACL;GACA,GAAG,qBAAqB,MAAM,WAAW;IACvC,SAAS,MAAM;IACf,eAAe,MAAM;IACtB,CAAC;GACF,GAAI,MAAM,UAAU,KAAA,KAAa,EAAE,OAAO,KAAK,OAAO;GACvD;;;CAIH,QAAQ,QAAiC;EACvC,OAAO,EAAE,QAAQ;;;CAInB,QAAQ,QAAiC;EACvC,OAAO,EAAE,QAAQ;;;CAInB,KAAK,QAAgB,MAA8C;EACjE,OAAO;GACL;GACA,GAAG,qBAAqB,MAAM,WAAW;IAAE,KAAK,MAAM;IAAK,KAAK,MAAM;IAAK,CAAC;GAC5E,GAAI,MAAM,UAAU,KAAA,KAAa,EAAE,OAAO,KAAK,OAAO;GACvD;;;CAIH,SAAS,QAAiC;EACxC,OAAO,EAAE,QAAQ;;;CAInB,MAAM,QAAiC;EACrC,OAAO,EAAE,QAAQ;;;CAInB,WAAW,KAAa,MAAmD;EACzE,OAAO;GACL,YAAY;GACZ,OAAO,KAAK;GACZ,GAAG,qBAAqB,KAAK,WAAW;IACtC,KAAK,KAAK;IACV,KAAK,KAAK;IACV,SAAS,KAAK;IACd,SAAS,KAAK;IACf,CAAC;GACH;;CAEJ;;;;;;;AAQD,SAAgB,UAAU,MAAkC;CAC1D,OAAO;EACL,SAAS,KAAK,OAAO,SAAS,UAAW,YAAY,QAAQ,CAAC,MAAM,OAAO,GAAG,EAAE,CAAE;EAClF,GAAI,KAAK,SAAS,KAAA,KAAa,EAAE,MAAM,KAAK,MAAM;EAClD,OAAO;EACP,QAAQ;GACN,UAAU,KAAK;GACf,QAAQ,KAAK;GACd;EACF;;;;;;AAOH,SAAS,qBACP,WACA,QACiB;CACjB,IAAI,CAAC,WAAW,OAAO,EAAE;CACzB,MAAM,WAAW,OAAO,YAAY,OAAO,QAAQ,OAAO,CAAC,QAAQ,GAAG,OAAO,MAAM,KAAA,EAAU,CAAC;CAC9F,OAAO;EACL;EACA,GAAI,OAAO,KAAK,SAAS,CAAC,SAAS,KAAK,EAAE,iBAAiB,UAAU;EACtE"}