@prisma-next/extension-paradedb 0.5.0-dev.9 → 0.5.1

package/src/contract.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "1",
+  "targetFamily": "sql",
+  "target": "postgres",
+  "profileHash": "sha256:1a8dbe044289f30a1de958fe800cc5a8378b285d2e126a8c44b58864bac2c18e",
+  "roots": {},
+  "models": {},
+  "storage": {
+    "storageHash": "sha256:7d13ea93bd4726b9962c00ced807a79149e3ff69e0a47d936c0e82f39a637393",
+    "tables": {}
+  },
+  "capabilities": {
+    "postgres": {
+      "jsonAgg": true,
+      "lateral": true,
+      "limit": true,
+      "orderBy": true,
+      "returning": true
+    },
+    "sql": {
+      "defaultInInsert": true,
+      "enums": true,
+      "returning": true
+    }
+  },
+  "extensionPacks": {},
+  "meta": {},
+  "_generated": {
+    "warning": "⚠️  GENERATED FILE - DO NOT EDIT",
+    "message": "This file is automatically generated by \"prisma-next contract emit\".",
+    "regenerate": "To regenerate, run: prisma-next contract emit"
+  }
+}

package/src/contract.prisma

@@ -0,0 +1,22 @@
+// PSL contract source for the `extension-paradedb` package.
+//
+// Authored against the contract-space package layout convention. The same
+// emit pipeline application authors use is applied here:
+//
+//   `prisma-next contract emit` → `<package>/src/contract.{json,d.ts}`
+//   `prisma-next migration plan` → `<package>/migrations/<dirName>/`
+//
+// The descriptor at `src/exports/control.ts` then wires the emitted JSON
+// artefacts via JSON-import declarations.
+//
+// ## IR coverage
+//
+// paradedb ships **no tables** and **no native types** of its own. Its
+// baseline migration installs the `pg_search` Postgres extension; all
+// BM25 index configuration is carried by the user contract's own models
+// (via the `'bm25'` index-type entry registered in `src/types/index-types.ts`).
+// The contract IR is therefore intentionally empty — the space is still
+// required so the migration runner can track the `pg_search` installation
+// invariant independently of any user models.
+//
+// @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md

package/src/core/constants.ts

@@ -4,19 +4,30 @@
 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`.
+ * Static names and identifiers used across paradedb's contract space.
+ *
+ * Centralised here so the contract IR (`./contract`), the baseline
+ * migration ops (`./migrations`), the head ref, and the descriptor
+ * (`../exports/control`) all reference the same values without typos.
+ *
+ * The space identifier `'paradedb'` is what the framework writes to
+ * `migrations/` in the user's repo and what the marker table's
+ * `space` column carries for paradedb-owned rows.
+ *
+ * The `paradedb:*` invariantId namespace is locked here — once
+ * published, an invariantId is immutable so downstream consumers can
+ * reference it by literal string match.
  */
-export type TokenizerId =
-  | 'unicode_words'
-  | 'simple'
-  | 'ngram'
-  | 'icu'
-  | 'regex_pattern'
-  | 'source_code'
-  | 'literal'
-  | 'literal_normalized'
-  | 'whitespace'
-  | 'chinese_compatible'
-  | 'jieba'
-  | 'lindera';
+export const PARADEDB_SPACE_ID = 'paradedb' as const;
+
+export const PARADEDB_BASELINE_MIGRATION_NAME =
+  '20260601T0000_install_pg_search_extension' as const;
+
+/**
+ * `paradedb:*` invariantIds emitted by the baseline migration. Each id,
+ * once published, is immutable: downstream consumers reference them by
+ * literal string match.
+ */
+export const PARADEDB_INVARIANTS = {
+  installPgSearch: 'paradedb:install-pg-search-v1',
+} as const;

package/src/core/descriptor-meta.ts

@@ -1,4 +1,194 @@
+import { LiteralExpr } from '@prisma-next/sql-relational-core/ast';
+import { buildOperation, toExpr } from '@prisma-next/sql-relational-core/expression';
+import { paradedbIndexTypes } from '../types/index-types';
+import type { QueryOperationTypes } from '../types/operation-types';
 import { PARADEDB_EXTENSION_ID } from './constants';
+import { ParadeDbProximityChain } from './proximity-chain';
+
+type CodecTypesBase = Record<string, { readonly input: unknown; readonly output: unknown }>;
+
+const TEXT = 'pg/text@1' as const;
+const BOOL = 'pg/bool@1' as const;
+const FLOAT4 = 'pg/float4@1' as const;
+const INT4 = 'pg/int4@1' as const;
+
+export function paradedbQueryOperations<CT extends CodecTypesBase>(): QueryOperationTypes<CT> {
+  return {
+    // `@@@` accepts both text and structured query types on its RHS.
+    // https://docs.paradedb.com/documentation/full-text/match
+    paradeDbMatch: {
+      self: { codecId: TEXT },
+      impl: (self, query) =>
+        buildOperation({
+          method: 'paradeDbMatch',
+          args: [toExpr(self, TEXT), toExpr(query, TEXT)],
+          returns: { codecId: BOOL, nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '{{self}} @@@ {{arg0}}',
+          },
+        }),
+    },
+    paradeDbMatchAny: {
+      self: { codecId: TEXT },
+      impl: (self, query) =>
+        buildOperation({
+          method: 'paradeDbMatchAny',
+          args: [toExpr(self, TEXT), toExpr(query, TEXT)],
+          returns: { codecId: BOOL, nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '{{self}} ||| {{arg0}}',
+          },
+        }),
+    },
+    paradeDbMatchAll: {
+      self: { codecId: TEXT },
+      impl: (self, query) =>
+        buildOperation({
+          method: 'paradeDbMatchAll',
+          args: [toExpr(self, TEXT), toExpr(query, TEXT)],
+          returns: { codecId: BOOL, nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '{{self}} &&& {{arg0}}',
+          },
+        }),
+    },
+    // https://docs.paradedb.com/documentation/full-text/term
+    paradeDbTerm: {
+      self: { codecId: TEXT },
+      impl: (self, query) =>
+        buildOperation({
+          method: 'paradeDbTerm',
+          args: [toExpr(self, TEXT), toExpr(query, TEXT)],
+          returns: { codecId: BOOL, nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '{{self}} === {{arg0}}',
+          },
+        }),
+    },
+    // https://docs.paradedb.com/documentation/full-text/phrase
+    paradeDbPhrase: {
+      self: { codecId: TEXT },
+      impl: (self, query) =>
+        buildOperation({
+          method: 'paradeDbPhrase',
+          args: [toExpr(self, TEXT), toExpr(query, TEXT)],
+          returns: { codecId: BOOL, nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '{{self}} ### {{arg0}}',
+          },
+        }),
+    },
+    // https://docs.paradedb.com/documentation/sorting/score
+    paradeDbScore: {
+      self: { codecId: INT4 },
+      impl: (self) =>
+        buildOperation({
+          method: 'paradeDbScore',
+          args: [toExpr(self, INT4)],
+          returns: { codecId: FLOAT4, nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: 'pdb.score({{self}})',
+          },
+        }),
+    },
+    // PG rejects parameterized typmods, so the cast argument lowers to a literal.
+    // https://docs.paradedb.com/documentation/full-text/fuzzy
+    paradeDbFuzzy: {
+      self: { codecId: TEXT },
+      impl: (self, distance) => {
+        if (!Number.isInteger(distance) || distance < 0 || distance > 2) {
+          throw new Error(
+            `paradeDbFuzzy: distance must be an integer in [0, 2]; got ${String(distance)}`,
+          );
+        }
+        return buildOperation({
+          method: 'paradeDbFuzzy',
+          args: [toExpr(self, TEXT), LiteralExpr.of(distance)],
+          returns: { codecId: TEXT, nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '{{self}}::pdb.fuzzy({{arg0}})',
+          },
+        });
+      },
+    },
+    // https://docs.paradedb.com/documentation/sorting/boost
+    paradeDbBoost: {
+      self: { codecId: TEXT },
+      impl: (self, weight) => {
+        if (!Number.isInteger(weight) || weight < -2048 || weight > 2048) {
+          throw new Error(
+            `paradeDbBoost: boost must be an integer in [-2048, 2048]; got ${String(weight)}`,
+          );
+        }
+        return buildOperation({
+          method: 'paradeDbBoost',
+          args: [toExpr(self, TEXT), LiteralExpr.of(weight)],
+          returns: { codecId: TEXT, nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '{{self}}::pdb.boost({{arg0}})',
+          },
+        });
+      },
+    },
+    paradeDbConst: {
+      self: { codecId: TEXT },
+      impl: (self, value) => {
+        if (!Number.isInteger(value)) {
+          throw new Error(`paradeDbConst: value must be an integer; got ${String(value)}`);
+        }
+        return buildOperation({
+          method: 'paradeDbConst',
+          args: [toExpr(self, TEXT), LiteralExpr.of(value)],
+          returns: { codecId: TEXT, nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '{{self}}::pdb.const({{arg0}})',
+          },
+        });
+      },
+    },
+    paradeDbSlop: {
+      self: { codecId: TEXT },
+      impl: (self, slop) => {
+        if (!Number.isInteger(slop) || slop < 0) {
+          throw new Error(`paradeDbSlop: slop must be a non-negative integer; got ${String(slop)}`);
+        }
+        return buildOperation({
+          method: 'paradeDbSlop',
+          args: [toExpr(self, TEXT), LiteralExpr.of(slop)],
+          returns: { codecId: TEXT, nullable: false },
+          lowering: {
+            targetFamily: 'sql',
+            strategy: 'function',
+            template: '{{self}}::pdb.slop({{arg0}})',
+          },
+        });
+      },
+    },
+    // https://docs.paradedb.com/documentation/full-text/proximity
+    paradeDbProximity: {
+      self: { codecId: TEXT },
+      impl: (start) => new ParadeDbProximityChain(start),
+    },
+  };
+}
 
 export const paradedbPackMeta = {
   kind: 'extension',
@@ -11,4 +201,14 @@ export const paradedbPackMeta = {
       'paradedb/bm25': true,
     },
   },
+  indexTypes: paradedbIndexTypes,
+  types: {
+    queryOperationTypes: {
+      import: {
+        package: '@prisma-next/extension-paradedb/operation-types',
+        named: 'QueryOperationTypes',
+        alias: 'ParadeDbQueryOperationTypes',
+      },
+    },
+  },
 } as const;

package/src/core/proximity-chain.ts

@@ -0,0 +1,83 @@
+import {
+  type AnyExpression,
+  LiteralExpr,
+  OperationExpr,
+} from '@prisma-next/sql-relational-core/ast';
+import { type Expression, toExpr } from '@prisma-next/sql-relational-core/expression';
+
+const TEXT = 'pg/text@1' as const;
+
+export type ProximityTerm = unknown;
+
+export interface ProximityWithinOptions {
+  readonly ordered?: boolean;
+}
+
+interface ProximityStep {
+  readonly distance: number;
+  readonly term: ProximityTerm;
+  readonly ordered: boolean;
+}
+
+// https://docs.paradedb.com/documentation/full-text/proximity
+export class ParadeDbProximityChain
+  implements Expression<{ codecId: 'pg/text@1'; nullable: false }>
+{
+  readonly returnType = { codecId: TEXT, nullable: false } as const;
+
+  private readonly start: ProximityTerm;
+  private readonly steps: readonly ProximityStep[];
+
+  constructor(start: ProximityTerm, steps: readonly ProximityStep[] = []) {
+    this.start = start;
+    this.steps = steps;
+  }
+
+  within(
+    distance: number,
+    term: ProximityTerm,
+    options?: ProximityWithinOptions,
+  ): ParadeDbProximityChain {
+    if (!Number.isInteger(distance) || distance < 0) {
+      throw new Error(
+        `paradeDbProximity.within: distance must be a non-negative integer; got ${String(distance)}`,
+      );
+    }
+    return new ParadeDbProximityChain(this.start, [
+      ...this.steps,
+      { distance, term, ordered: options?.ordered === true },
+    ]);
+  }
+
+  buildAst(): AnyExpression {
+    if (this.steps.length === 0) {
+      throw new Error(
+        'paradeDbProximity: chain must have at least one .within(distance, term) step',
+      );
+    }
+    const args: AnyExpression[] = [toExpr(this.start, TEXT)];
+    let template = '({{self}}';
+    this.steps.forEach((step, i) => {
+      const op = step.ordered ? '##>' : '##';
+      args.push(LiteralExpr.of(step.distance));
+      args.push(toExpr(step.term, TEXT));
+      template += ` ${op} {{arg${2 * i}}} ${op} {{arg${2 * i + 1}}}`;
+    });
+    template += ')';
+    const [self, ...rest] = args;
+    if (!self) {
+      throw new Error('paradeDbProximity: invariant violation — empty args');
+    }
+    return new OperationExpr({
+      method: 'paradeDbProximity',
+      self,
+      args: rest.length > 0 ? rest : undefined,
+      returns: this.returnType,
+      lowering: {
+        targetFamily: 'sql',
+        strategy: 'function',
+        template,
+      },
+    });
+  }
+}

package/src/exports/control.ts

@@ -1,3 +1,71 @@
-import { paradedbPackMeta } from '../core/descriptor-meta';
+/**
+ * Control-plane descriptor for the paradedb extension.
+ *
+ * **Contract-space package layout.** The extension's contract
+ * + migrations are emitted by the same pipeline application authors use:
+ *
+ *   `prisma-next contract emit` → `<package>/src/contract.{json,d.ts}`
+ *   `prisma-next migration plan` → `<package>/migrations/<dir>/...`
+ *
+ * The descriptor wires those JSON artefacts via JSON-import declarations
+ * so they flow through the consuming application's module resolver
+ * without filesystem assumptions, and synthesises the canonical
+ * {@link import('@prisma-next/framework-components/control').MigrationPackage}
+ * shape for the framework's runner / verifier to consume. Readers in
+ * `@prisma-next/migration-tools` add `dirPath` when loading from disk
+ * (`OnDiskMigrationPackage`); descriptor-bundled packages do not need
+ * it because the framework reads them directly from the descriptor.
+ *
+ * Wired surfaces:
+ *
+ *   - `contractSpace.{contractJson,migrations,headRef}` — sourced from
+ *     the on-disk artefacts emitted by `build:contract-space`.
+ *   - `queryOperations` — BM25 full-text search operations registered
+ *     via `paradedbQueryOperations()`.
+ *
+ * @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md
+ *   (contract-space package layout convention).
+ */
 
-export { paradedbPackMeta };
+import type { Contract } from '@prisma-next/contract/types';
+import type { SqlControlExtensionDescriptor } from '@prisma-next/family-sql/control';
+import { contractSpaceFromJson } from '@prisma-next/migration-tools/spaces';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import baselineMetadata from '../../migrations/20260601T0000_install_pg_search_extension/migration.json' with {
+  type: 'json',
+};
+import baselineOps from '../../migrations/20260601T0000_install_pg_search_extension/ops.json' with {
+  type: 'json',
+};
+import headRef from '../../migrations/refs/head.json' with { type: 'json' };
+import contractJson from '../contract.json' with { type: 'json' };
+import { PARADEDB_SPACE_ID } from '../core/constants';
+import { paradedbPackMeta, paradedbQueryOperations } from '../core/descriptor-meta';
+
+const BASELINE_DIR_NAME = '20260601T0000_install_pg_search_extension';
+
+const paradedbContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
+  contractJson,
+  migrations: [
+    {
+      dirName: BASELINE_DIR_NAME,
+      metadata: baselineMetadata,
+      ops: baselineOps,
+    },
+  ],
+  headRef,
+});
+
+const paradedbExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'> = {
+  ...paradedbPackMeta,
+  id: PARADEDB_SPACE_ID,
+  contractSpace: paradedbContractSpace,
+  queryOperations: () => paradedbQueryOperations(),
+  create: () => ({
+    familyId: 'sql' as const,
+    targetId: 'postgres' as const,
+  }),
+};
+
+export { paradedbExtensionDescriptor, paradedbPackMeta };
+export default paradedbExtensionDescriptor;

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/exports/operation-types.ts

@@ -0,0 +1 @@
+export type { QueryOperationTypes } from '../types/operation-types';

package/src/exports/runtime.ts

@@ -0,0 +1,20 @@
+import type { SqlRuntimeExtensionDescriptor } from '@prisma-next/sql-runtime';
+import { paradedbPackMeta, paradedbQueryOperations } from '../core/descriptor-meta';
+
+const paradedbRuntimeDescriptor: SqlRuntimeExtensionDescriptor<'postgres'> = {
+  kind: 'extension' as const,
+  id: paradedbPackMeta.id,
+  version: paradedbPackMeta.version,
+  familyId: 'sql' as const,
+  targetId: 'postgres' as const,
+  codecs: () => [],
+  queryOperations: () => paradedbQueryOperations(),
+  create() {
+    return {
+      familyId: 'sql' as const,
+      targetId: 'postgres' as const,
+    };
+  },
+};
+
+export default paradedbRuntimeDescriptor;