@vibeorm/extensions 2.0.0-alpha.1

package/README.md

@@ -0,0 +1,167 @@
+# @vibeorm/extensions
+
+> A type-safe TypeScript ORM for Bun and Node. Prisma-schema or TypeScript-DSL input, a canonical schema IR, a generated client that your editor never re-infers, and a dialect-aware SQL layer over PostgreSQL, PGlite, SQLite and MySQL.
+
+```bash
+bun add @vibeorm/extensions@alpha
+```
+
+> **Pre-release.** `2.0.0-alpha.x`, published under the `alpha` dist-tag. `npm i vibeorm` still resolves to the stable v1 line, which has a different API — see the migration guide below.
+
+## What it provides
+
+Three extensions, each a factory returning a `VibeExtension` that you pass to `vibeorm.config.ts` (so `generate`, `db push`, `migrate` and `doctor` see it) and to `VibeClient` (so the runtime mounts it).
+
+| Import | Factory | Databases |
+|---|---|---|
+| `@vibeorm/extensions/search` | `search(options?)` | PostgreSQL, PGlite, SQLite, MySQL |
+| `@vibeorm/extensions/vector` | `vector(options?)` | PostgreSQL, PGlite (pgvector) |
+| `@vibeorm/extensions/trgm` | `trgm(options?)` | PostgreSQL, PGlite (pg_trgm) |
+
+The package root (`@vibeorm/extensions`) re-exports all three for convenience.
+
+```ts
+// vibeorm.config.ts
+import { search } from "@vibeorm/extensions/search";
+import { trgm } from "@vibeorm/extensions/trgm";
+import { vector } from "@vibeorm/extensions/vector";
+
+export default {
+  schema: "./prisma/schema.prisma",
+  output: "./generated/vibeorm",
+  extensions: [search(), trgm({ threshold: 0.3 }), vector()],
+};
+```
+
+Each extension declares its schema attributes, the DDL artifacts `db push` / `migrate` apply, and the surface the generator writes into the client's `.d.ts`. You declare usage in the schema; the client method or namespace appears only on the models that declare it.
+
+## Search
+
+Declare the searched fields with `@@search`. Optional named arguments: `name` (artifact base name, a plain identifier), `weights` (one number per field), `language` (a text-search config name, tsvector engine only).
+
+```prisma
+model Post {
+  id        Int     @id @default(autoincrement())
+  title     String
+  body      String
+  published Boolean @default(true)
+
+  @@search([title, body], weights: [2, 1])
+}
+```
+
+```ts
+import { VibeClient } from "./generated/vibeorm/index.js";
+import { search } from "@vibeorm/extensions/search";
+
+const db = VibeClient({ adapter, extensions: [search()] });
+
+const hits = await db.post.search({
+  query: "database indexes",
+  where: { published: true },
+  take: 10,
+  skip: 0,
+  minScore: 0.1,
+  highlight: { field: "body" },
+});
+// hits: SearchHit<Post>[] — { row, score, highlights }
+```
+
+`highlights` is `readonly string[] | null`; it is `null` when no highlight was requested and on engines without highlighting.
+
+### Engines per dialect
+
+`engine: "auto"` (the default) picks the dialect's native engine. `resolveSearchEngine({ dialect, provider, requested })` is the exported resolution rule.
+
+| Dialect | Engine | SQL used | Highlights |
+|---|---|---|---|
+| postgres / pglite | `tsvector` | generated `STORED` tsvector column + GIN index, `websearch_to_tsquery` / `ts_rank_cd` / `ts_headline` | yes |
+| postgres (ParadeDB `pg_search`, opt in with `search({ engine: "bm25" })`) | `bm25` | bm25 index, `@@@`, `paradedb.score` / `paradedb.snippet` | yes |
+| sqlite | `fts5` | external-content virtual table + sync triggers, `MATCH` / `bm25()` / `snippet()` | yes |
+| mysql | `fulltext` | `FULLTEXT` index, `MATCH … AGAINST` in natural language mode | no, typed `null` |
+
+Two gates worth knowing before you pick a dialect:
+
+- `engine: "bm25"` is refused on `pglite` (it does not bundle `pg_search`) and on non-postgres dialects. `"auto"` never selects it, because ParadeDB availability is not knowable at generate time.
+- The `fts5` engine requires the searched model to have a single `Int` or `BigInt` `@id`. That is the only primary key that aliases and pins the SQLite rowid the external-content table keys on; anything else is refused at generate time.
+
+`createSearchDelegate(config)` is the runtime glue the generator emits into the client. You do not call it by hand.
+
+## Vector
+
+pgvector similarity search, on PostgreSQL and PGlite only. Declare a `Vector(n)` field and an index with `@@vector`. Named arguments: `metric` (`"cosine"` default, `"l2"`, `"ip"`), `index` (`"hnsw"` default or `"ivfflat"`), plus `m` / `efConstruction` for hnsw and `lists` for ivfflat.
+
+```prisma
+model Doc {
+  id        Int       @id @default(autoincrement())
+  tenantId  String
+  embedding Vector(3)?
+
+  @@vector([embedding], metric: "cosine", index: "hnsw")
+}
+```
+
+```ts
+import { vector } from "@vibeorm/extensions/vector";
+
+const db = VibeClient({ adapter, extensions: [vector()] });
+
+await db.doc.vector.set({ where: { id: 1 }, by: "embedding", to: [1, 0, 0] });
+
+const near = await db.doc.vector.nearest({
+  by: "embedding",
+  to: [1, 0, 0],
+  take: 10,
+  where: { tenantId: "t2" },
+  maxDistance: 0.4,
+});
+// near: VectorHit<Doc>[] — { row, distance }, smaller distance is closer
+```
+
+`set` returns the number of updated rows. `nearest` takes an optional `metric` that overrides the schema's default per query. A `to` array whose length does not match the column's declared dimensions is a `VibeError` with code `VIBE_VALIDATION`. `createVectorNamespace(config)` is the generated glue; `VectorMetric` and `VectorHit` are the exported types the client's `.d.ts` imports.
+
+## Trgm
+
+pg_trgm fuzzy matching, on PostgreSQL and PGlite only. It claims no client surface: it adds the `similarTo` where-operator and `gin_trgm_ops` indexes over the fields listed in `@@trgm`.
+
+```prisma
+model User {
+  id   Int    @id @default(autoincrement())
+  name String
+
+  @@trgm([name])
+}
+```
+
+```ts
+import { trgm } from "@vibeorm/extensions/trgm";
+
+const db = VibeClient({ adapter, extensions: [trgm({ threshold: 0.3 })] });
+
+await db.user.findMany({ where: { name: { similarTo: "jonatan" } } });
+await db.user.findMany({ where: { name: { similarTo: { text: "jonatan", threshold: 0.95 } } } });
+```
+
+The operand is a `SimilarToOperand`: a string, or `{ text, threshold? }` for a per-use threshold. `threshold` in `TrgmOptions` sets the default (0.3) and is applied to the session's `pg_trgm.similarity_threshold` on connect.
+
+The compiled predicate has two forms. When the effective threshold is at least `max(configured, 0.3)` it emits `col % $q AND similarity(col, $q) >= $t`, so the trigram index prunes. Below that floor it emits `similarity(col, $q) >= $t` alone, which is a full scan but returns every row the caller asked for, because a pooled connection may still carry the server's 0.3 default. `vibeorm doctor` reports whether the server's `pg_trgm.similarity_threshold` sits above the gate floor.
+
+## Capability gating
+
+A feature a dialect cannot express throws a `VibeError` with code `VIBE_UNSUPPORTED_CAPABILITY` at the earliest knowable moment: generate or migrate time when the schema alone decides it, execute time otherwise. Nothing degrades silently.
+
+- `vector()` on sqlite or mysql fails when artifacts are built and when the client is generated, before any DDL reaches the database.
+- `trgm()` fails the same way, and `similarTo` refuses to compile on a non-postgres dialect.
+- `search({ engine })` fails at engine resolution when the requested engine is not the dialect's native one (and is not `bm25` on a non-pglite postgres).
+
+`vibeorm doctor` reports per-extension checks: `pg_search`, `vector` and `pg_trgm` availability from `pg_available_extensions`, FTS5 compilation on SQLite, and the trgm threshold check described above.
+
+## Links
+
+- [Documentation](https://github.com/vibeorm/vibeorm/tree/master/docs)
+- [Getting started](https://github.com/vibeorm/vibeorm/blob/master/docs/getting-started.md)
+- [Query API](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md)
+- [Coming from Prisma](https://github.com/vibeorm/vibeorm/blob/master/docs/from-prisma.md)
+- [Upgrading from VibeORM v1](https://github.com/vibeorm/vibeorm/blob/master/docs/migrating-v1-v2.md)
+- [Repository and issues](https://github.com/vibeorm/vibeorm)
+- MIT licensed

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @vibeorm/extensions — tier-1 VibeORM extensions (plan §10, extensions.md).
+ *
+ * Import from the subpaths in app code (`@vibeorm/extensions/search`, …, D6);
+ * this root re-exports everything for convenience and for the CLI/tests.
+ */
+export { createSearchDelegate, resolveSearchEngine, search } from "./search/index.ts";
+export type { SearchArgs, SearchDelegateConfig, SearchEngine, SearchHit, SearchMethod, SearchOptions, } from "./search/index.ts";
+export { createVectorNamespace, vector } from "./vector/index.ts";
+export type { VectorHit, VectorMetric, VectorNamespace, VectorNamespaceConfig, VectorNearestArgs, VectorOptions, VectorSetArgs, } from "./vector/index.ts";
+export { trgm } from "./trgm/index.ts";
+export type { SimilarToOperand, TrgmOptions } from "./trgm/index.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACtF,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAClE,YAAY,EACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}