{"version":3,"file":"contract.cjs","names":[],"sources":["../../../src/batteries/vector/contract.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/contract\n */\n\nimport { VectorQueryBuilder, type PlanSink } from './builder'\nimport { VectorSchemaBuilder, type SchemaExecutor } from './schema'\nimport {\n  E_VECTOR_STORE_ENCODER_REQUIRED,\n  E_VECTOR_STORE_TRANSACTIONS_UNSUPPORTED,\n} from './exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from './plan'\nimport type {\n  VectorMatch,\n  BaseVectorStoreOptions,\n  VectorStoreCapabilities,\n  EncodeKind,\n} from './types'\n\n/**\n * Opaque handle for a backend transaction. Stores that support transactions return a\n * driver-specific implementation; the harness only passes it back through {@link VectorStore.transaction}.\n */\nexport interface VectorTx {}\n\n/**\n * The public surface every vector store exposes: capability flags, lifecycle (`connect`/`close`),\n * a callable form that opens a {@link VectorQueryBuilder} for a collection, schema access, and an\n * optional transaction wrapper. Adapters extend {@link BaseVectorStore}, which implements this plus\n * the low-level plan/schema executor contracts.\n */\nexport interface VectorStore extends PlanSink, SchemaExecutor {\n  /** Static description of what this backend supports (built-in encoding, transactions, filters, etc.). */\n  readonly capabilities: VectorStoreCapabilities\n  /** Whether the backend's optional peer dependency is installed and the store is usable. */\n  isAvailable(): boolean\n  /** Open the backing connection (clients, pools, sockets). */\n  connect(): Promise<void>\n  /** Release the backing connection and any held resources. */\n  close(): Promise<void>\n  /** Callable form: `store('collection')` returns a query builder scoped to that collection. */\n  (collection: string): VectorQueryBuilder\n  /** Schema builder for creating, dropping, and migrating collections. */\n  schema: VectorSchemaBuilder\n  /** Run `fn` inside a backend transaction, where supported; rejects otherwise. */\n  transaction(fn: (tx: VectorStore) => Promise<void>): Promise<void>\n}\n\n/**\n * Abstract base shared by every bundled vector adapter. It implements the cross-cutting surface\n * (`query`/`schema`/`transaction`/`asCallable`/`encode`) on top of the small set of backend-specific\n * abstract methods each adapter fills in (`connect`, `executeSearch`, `createCollection`, …). Concrete\n * adapters inherit the doc comments below unless they override them.\n */\nexport abstract class BaseVectorStore implements PlanSink, SchemaExecutor {\n  /** Static description of what this backend supports — see {@link VectorStoreCapabilities}. */\n  abstract readonly capabilities: VectorStoreCapabilities\n  /** Construction options (connection details and the optional encoder), held for later use. */\n  protected options: BaseVectorStoreOptions\n\n  constructor(options: BaseVectorStoreOptions) {\n    this.options = options\n  }\n\n  /** Whether the backend's optional peer dependency is installed and the store is usable. */\n  abstract isAvailable(): boolean\n  /** Establish the backing connection (open clients, pools, sockets). Idempotent where the driver allows. */\n  abstract connect(): Promise<void>\n  /** Release the backing connection and any held resources. */\n  abstract close(): Promise<void>\n\n  /** Execute a compiled search plan and return the matched records. */\n  abstract executeSearch(plan: SearchPlan): Promise<VectorMatch[]>\n  /** Execute a compiled upsert plan (insert-or-replace the given records). */\n  abstract executeUpsert(plan: UpsertPlan): Promise<void>\n  /** Execute a compiled delete plan. */\n  abstract executeDelete(plan: DeletePlan): Promise<void>\n\n  /** Create a collection from `spec`; a no-op when `ifNotExists` and it already exists. */\n  abstract createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void>\n  /** Drop a collection; a no-op when `ifExists` and it is absent. */\n  abstract dropCollection(collection: string, ifExists: boolean): Promise<void>\n  /** Whether a collection currently exists in the backend. */\n  abstract hasCollection(collection: string): Promise<boolean>\n  /** Rename a collection from `from` to `to`. */\n  abstract renameCollection(from: string, to: string): Promise<void>\n\n  /**\n   * Encode text to vectors via the configured encoder. Throws {@link E_VECTOR_STORE_ENCODER_REQUIRED}\n   * when the backend has no built-in encoding and no encoder was supplied.\n   */\n  protected async encode(texts: string[], kind: EncodeKind): Promise<number[][]> {\n    if (this.capabilities.builtInEncoding) {\n      throw new E_VECTOR_STORE_ENCODER_REQUIRED(['contract'])\n    }\n    if (!this.options.encoder) throw new E_VECTOR_STORE_ENCODER_REQUIRED([this.constructor.name])\n    return this.options.encoder(texts, kind)\n  }\n\n  /**\n   * Run `fn` inside a backend transaction. The base implementation rejects with\n   * {@link E_VECTOR_STORE_TRANSACTIONS_UNSUPPORTED}; adapters whose backend supports transactions\n   * override this.\n   */\n  async transaction(_fn: (tx: CallableVectorStore) => Promise<void>): Promise<void> {\n    throw new E_VECTOR_STORE_TRANSACTIONS_UNSUPPORTED([this.constructor.name])\n  }\n\n  /** Schema builder bound to this store, for creating/dropping/migrating collections. */\n  get schema(): VectorSchemaBuilder {\n    return new VectorSchemaBuilder(this)\n  }\n\n  /** Open a {@link VectorQueryBuilder} scoped to `collection` (default top-K of 10). */\n  query(collection: string): VectorQueryBuilder {\n    const defaultTopK = 10\n    return new VectorQueryBuilder(this, collection, defaultTopK)\n  }\n\n  /**\n   * Wrap this store in a callable proxy so `store('collection')` is shorthand for\n   * `store.query('collection')`, while all other methods/properties pass through unchanged.\n   */\n  asCallable(): CallableVectorStore {\n    const self = this\n    const fn = ((collection: string) => self.query(collection)) as CallableVectorStore\n    return new Proxy(fn, {\n      get(target, prop, receiver) {\n        if (prop in target) return Reflect.get(target, prop, receiver)\n        const val = (self as any)[prop]\n        return typeof val === 'function' ? val.bind(self) : val\n      },\n    })\n  }\n}\n\n/** A {@link VectorStore} in its callable form — `store('collection')` opens a query builder. */\nexport type CallableVectorStore = ((collection: string) => VectorQueryBuilder) & VectorStore\n"],"mappings":";;;;;;;;;;;;;;;AAqDA,IAAsB,kBAAtB,MAA0E;;CAIxE;CAEA,YAAY,SAAiC;EAC3C,KAAK,UAAU;CACjB;;;;;CA6BA,MAAgB,OAAO,OAAiB,MAAuC;EAC7E,IAAI,KAAK,aAAa,iBACpB,MAAM,IAAI,oCAAA,gCAAgC,CAAC,UAAU,CAAC;EAExD,IAAI,CAAC,KAAK,QAAQ,SAAS,MAAM,IAAI,oCAAA,gCAAgC,CAAC,KAAK,YAAY,IAAI,CAAC;EAC5F,OAAO,KAAK,QAAQ,QAAQ,OAAO,IAAI;CACzC;;;;;;CAOA,MAAM,YAAY,KAAgE;EAChF,MAAM,IAAI,oCAAA,wCAAwC,CAAC,KAAK,YAAY,IAAI,CAAC;CAC3E;;CAGA,IAAI,SAA8B;EAChC,OAAO,IAAI,gCAAA,oBAAoB,IAAI;CACrC;;CAGA,MAAM,YAAwC;EAE5C,OAAO,IAAI,iCAAA,mBAAmB,MAAM,YAAY,EAAW;CAC7D;;;;;CAMA,aAAkC;EAChC,MAAM,OAAO;EACb,MAAM,OAAO,eAAuB,KAAK,MAAM,UAAU;EACzD,OAAO,IAAI,MAAM,IAAI,EACnB,IAAI,QAAQ,MAAM,UAAU;GAC1B,IAAI,QAAQ,QAAQ,OAAO,QAAQ,IAAI,QAAQ,MAAM,QAAQ;GAC7D,MAAM,MAAO,KAAa;GAC1B,OAAO,OAAO,QAAQ,aAAa,IAAI,KAAK,IAAI,IAAI;EACtD,EACF,CAAC;CACH;AACF"}