turbine-orm 0.16.0 → 0.19.0

package/dist/query/index.d.ts

@@ -5,7 +5,7 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, JsonFilter, NestedCreateOp, NestedUpdateOp, OmitResult, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, SelectResult, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
+export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, JsonFilter, NestedCreateOp, NestedUpdateOp, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, SelectResult, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';

package/dist/query/types.d.ts

@@ -27,8 +27,9 @@ export interface WhereOperator<V = unknown> {
  * - A JSONB filter object ({ contains, equals, path, hasKey })
  * - An array filter object ({ has, hasEvery, hasSome, isEmpty })
  * - A text search filter object ({ search, config? })
+ * - A vector distance filter object ({ distance: { to, metric, lt } }) for pgvector columns
  */
-export type WhereValue<V = unknown> = V | WhereOperator<V> | JsonFilter | ArrayFilter | TextSearchFilter | null;
+export type WhereValue<V = unknown> = V | WhereOperator<V> | JsonFilter | ArrayFilter | TextSearchFilter | VectorFilter | null;
 /**
  * Where clause type: each field can be a plain value, null, or operator object.
  * Special keys: OR for disjunctive conditions.
@@ -197,7 +198,7 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
     where?: WhereClause<T>;
     select?: S;
     omit?: O;
-    orderBy?: Record<string, OrderDirection>;
+    orderBy?: OrderByClause;
     limit?: number;
     offset?: number;
     with?: W;
@@ -352,6 +353,59 @@ export interface CountArgs<T> {
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
 }
+/**
+ * Numeric comparison operators usable inside a `having` filter. A bare number
+ * is shorthand for equality (`COUNT(*) = $n`); the operator object supports
+ * range and inequality comparisons. Mirrors the numeric subset of
+ * {@link WhereOperator} so the same SQL machinery can be reused.
+ */
+export interface HavingNumericOperator {
+    equals?: number;
+    not?: number;
+    gt?: number;
+    gte?: number;
+    lt?: number;
+    lte?: number;
+    in?: number[];
+    notIn?: number[];
+}
+/** A single having predicate value: a bare number (equality) or an operator object. */
+export type HavingFilter = number | HavingNumericOperator;
+/**
+ * Per-field aggregate filters inside a {@link HavingClause}. Each aggregate
+ * function maps to a {@link HavingFilter} comparison on that field.
+ *
+ * @example
+ *   viewCount: { _sum: { gt: 100 }, _avg: { lte: 50 } }
+ */
+export interface HavingAggregateFilter {
+    _sum?: HavingFilter;
+    _avg?: HavingFilter;
+    _min?: HavingFilter;
+    _max?: HavingFilter;
+    _count?: HavingFilter;
+}
+/**
+ * HAVING clause for `groupBy` — filters whole groups by their aggregate values
+ * (the SQL `HAVING` clause). Follows Prisma's shape: each aggregable field maps
+ * to a {@link HavingAggregateFilter} (`field → aggregate → operator → value`),
+ * and the special top-level `_count` key (no field) filters on `COUNT(*)`.
+ *
+ * Implemented as a mapped type so the special `_count` key can carry a
+ * {@link HavingFilter} while every entity field carries a
+ * {@link HavingAggregateFilter} — without the index-signature conflict an
+ * intersection type would produce when `T` is a broad `Record<string, unknown>`.
+ *
+ * @example
+ *   // groups with more than 5 rows whose summed viewCount is at least 100
+ *   having: { _count: { gt: 5 }, viewCount: { _sum: { gte: 100 } } }
+ */
+export type HavingClause<T> = {
+    /** Filter on `COUNT(*)` for the whole group. */
+    _count?: HavingFilter;
+} & {
+    [K in keyof T & string]?: HavingAggregateFilter;
+};
 export interface GroupByArgs<T> {
     by: (keyof T & string)[];
     where?: WhereClause<T>;
@@ -365,6 +419,8 @@ export interface GroupByArgs<T> {
     _min?: Partial<Record<keyof T & string, boolean>>;
     /** Maximum value of fields in each group */
     _max?: Partial<Record<keyof T & string, boolean>>;
+    /** Filter whole groups by their aggregate values (SQL HAVING). */
+    having?: HavingClause<T>;
     /** Order groups */
     orderBy?: Record<string, OrderDirection>;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
@@ -429,5 +485,73 @@ export interface TextSearchFilter {
     /** PostgreSQL text search configuration name (defaults to 'english') */
     config?: string;
 }
+/**
+ * Vector distance metric. Maps to a pgvector distance operator:
+ *
+ *  - `'l2'`     → `<->` (Euclidean / L2 distance)
+ *  - `'cosine'` → `<=>` (cosine distance)
+ *  - `'ip'`     → `<#>` (negative inner product)
+ *
+ * This is a fixed allow-list — a value outside it is rejected with a
+ * `ValidationError` so a user-supplied string can never become a SQL operator.
+ */
+export type VectorMetric = 'l2' | 'cosine' | 'ip';
+/**
+ * Distance threshold filter for a pgvector column inside a `where` clause:
+ *
+ * ```ts
+ * where: { embedding: { distance: { to: [0.1, 0.2, 0.3], metric: 'l2', lt: 0.3 } } }
+ * // → WHERE "embedding" <-> $1::vector < $2
+ * ```
+ *
+ * `to` is always bound as a single `$n::vector` param (never interpolated) and
+ * each element must be a finite number. Exactly one comparison
+ * (`lt` / `lte` / `gt` / `gte`) is applied; the threshold is also a bound param.
+ */
+export interface VectorDistanceFilter {
+    /** The query vector to measure distance against. */
+    to: number[];
+    /** Distance metric → operator. */
+    metric: VectorMetric;
+    /** distance < threshold */
+    lt?: number;
+    /** distance <= threshold */
+    lte?: number;
+    /** distance > threshold */
+    gt?: number;
+    /** distance >= threshold */
+    gte?: number;
+}
+/** Vector query operators for where clauses (pgvector). */
+export interface VectorFilter {
+    /** Filter rows by distance from a query vector. */
+    distance: VectorDistanceFilter;
+}
+/**
+ * KNN ordering spec for a pgvector column inside an `orderBy` clause:
+ *
+ * ```ts
+ * orderBy: { embedding: { distance: { to: [...], metric: 'cosine' } } }
+ * // → ORDER BY "embedding" <=> $1::vector ASC
+ * ```
+ *
+ * `distance` ASC ranks nearest-first (the default). Pass `direction: 'desc'`
+ * to invert. The query vector `to` is bound as a `$n::vector` param.
+ */
+export interface VectorOrderByDistance {
+    to: number[];
+    metric: VectorMetric;
+    /** Sort direction for the computed distance. Defaults to `'asc'` (nearest first). */
+    direction?: OrderDirection;
+}
+/** Per-column orderBy value: a plain direction or a vector-distance ordering. */
+export interface VectorOrderBy {
+    distance: VectorOrderByDistance;
+}
+/**
+ * An orderBy clause maps each column to either a plain direction (`'asc'` /
+ * `'desc'`) or, for pgvector columns, a KNN distance ordering object.
+ */
+export type OrderByClause = Record<string, OrderDirection | VectorOrderBy>;
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/realtime.d.ts

@@ -0,0 +1,71 @@
+/**
+ * turbine-orm — LISTEN/NOTIFY realtime pub/sub
+ *
+ * Postgres LISTEN/NOTIFY is a first-class realtime primitive that neither
+ * Prisma nor Drizzle expose ergonomically. This module backs the thin
+ * `$listen` / `$notify` methods on TurbineClient.
+ *
+ * Design — **one dedicated connection per subscription**:
+ *
+ *   Each `$listen(channel, handler)` acquires its OWN long-lived client from
+ *   the pool, runs `LISTEN "chan"`, and keeps that connection checked out for
+ *   the life of the subscription. This is the simplest correct model: each
+ *   subscription owns its lifecycle, `unsubscribe()` cleanly UNLISTENs and
+ *   releases exactly one connection, and there is no shared multiplexing
+ *   state to reason about. The trade-off is one pool slot per active channel
+ *   — for the handful of channels a typical app listens on, that's a fine
+ *   price for clarity. (A future optimization could multiplex many channels
+ *   over a single shared notification connection.)
+ *
+ * Serverless / HTTP-pool caveat:
+ *
+ *   LISTEN requires a *persistent* TCP connection that can push asynchronous
+ *   notification messages back to the client. Stateless HTTP drivers
+ *   (Neon HTTP, Vercel Postgres over fetch) cannot hold such a connection, so
+ *   `$listen` will surface a clear error rather than hang. `$notify` works
+ *   everywhere — it's a single round-trip `SELECT pg_notify(...)`.
+ */
+import type { PgCompatPool } from './client.js';
+/**
+ * Validate a LISTEN/NOTIFY channel name. Throws ValidationError on anything
+ * that isn't a plain, reasonable-length SQL identifier. This is enforced for
+ * BOTH `$listen` (where the channel is interpolated) and `$notify` (where the
+ * channel is a bound param) — defensive parity, and it catches user typos
+ * loudly.
+ */
+export declare function validateChannel(channel: string): void;
+/** Handler invoked with the raw NOTIFY payload string (empty string if none). */
+export type NotificationHandler = (payload: string) => void;
+/**
+ * A live LISTEN subscription. Call `unsubscribe()` to UNLISTEN, detach the
+ * handler, and release the dedicated connection back to the pool.
+ */
+export interface Subscription {
+    /** The channel this subscription is listening on. */
+    readonly channel: string;
+    /**
+     * Stop listening: runs `UNLISTEN "chan"`, removes the notification listener,
+     * and releases the dedicated connection. Idempotent — safe to call twice.
+     */
+    unsubscribe(): Promise<void>;
+}
+/**
+ * Internal registry handle so TurbineClient can track and tear down active
+ * subscriptions on `disconnect()`.
+ */
+export interface ActiveSubscription extends Subscription {
+    /** Tear down WITHOUT issuing UNLISTEN (used when the pool is being ended). */
+    _forceRelease(): void;
+}
+/**
+ * Acquire a dedicated connection, run `LISTEN "channel"`, and wire the handler.
+ *
+ * @param pool        the pg-compatible pool to check a long-lived client out of
+ * @param channel     channel name — MUST already be validated by the caller
+ * @param quotedChannel  the channel run through quoteIdent (interpolated into SQL)
+ * @param handler     called with each notification's payload
+ * @param onClosed    invoked when the subscription releases, so the client can
+ *                    drop it from its active-subscription registry
+ */
+export declare function createSubscription(pool: PgCompatPool, channel: string, quotedChannel: string, handler: NotificationHandler, onClosed: (sub: ActiveSubscription) => void): Promise<ActiveSubscription>;
+//# sourceMappingURL=realtime.d.ts.map

package/dist/realtime.js

@@ -0,0 +1,144 @@
+/**
+ * turbine-orm — LISTEN/NOTIFY realtime pub/sub
+ *
+ * Postgres LISTEN/NOTIFY is a first-class realtime primitive that neither
+ * Prisma nor Drizzle expose ergonomically. This module backs the thin
+ * `$listen` / `$notify` methods on TurbineClient.
+ *
+ * Design — **one dedicated connection per subscription**:
+ *
+ *   Each `$listen(channel, handler)` acquires its OWN long-lived client from
+ *   the pool, runs `LISTEN "chan"`, and keeps that connection checked out for
+ *   the life of the subscription. This is the simplest correct model: each
+ *   subscription owns its lifecycle, `unsubscribe()` cleanly UNLISTENs and
+ *   releases exactly one connection, and there is no shared multiplexing
+ *   state to reason about. The trade-off is one pool slot per active channel
+ *   — for the handful of channels a typical app listens on, that's a fine
+ *   price for clarity. (A future optimization could multiplex many channels
+ *   over a single shared notification connection.)
+ *
+ * Serverless / HTTP-pool caveat:
+ *
+ *   LISTEN requires a *persistent* TCP connection that can push asynchronous
+ *   notification messages back to the client. Stateless HTTP drivers
+ *   (Neon HTTP, Vercel Postgres over fetch) cannot hold such a connection, so
+ *   `$listen` will surface a clear error rather than hang. `$notify` works
+ *   everywhere — it's a single round-trip `SELECT pg_notify(...)`.
+ */
+import { ConnectionError, ValidationError, wrapPgError } from './errors.js';
+// ---------------------------------------------------------------------------
+// Identifier validation
+// ---------------------------------------------------------------------------
+/**
+ * Strict Postgres identifier: a letter or underscore followed by letters,
+ * digits, or underscores. Channel names CANNOT be parameterized in
+ * LISTEN/UNLISTEN (`LISTEN $1` is a syntax error), so the channel is the one
+ * place an identifier is interpolated into SQL — it MUST pass this regex AND
+ * go through `quoteIdent` before reaching the SQL string.
+ */
+const CHANNEL_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Postgres NAMEDATALEN caps identifiers at 63 bytes. */
+const MAX_CHANNEL_LEN = 63;
+/**
+ * Validate a LISTEN/NOTIFY channel name. Throws ValidationError on anything
+ * that isn't a plain, reasonable-length SQL identifier. This is enforced for
+ * BOTH `$listen` (where the channel is interpolated) and `$notify` (where the
+ * channel is a bound param) — defensive parity, and it catches user typos
+ * loudly.
+ */
+export function validateChannel(channel) {
+    if (typeof channel !== 'string' || channel.length === 0) {
+        throw new ValidationError('[turbine] $listen/$notify channel must be a non-empty string');
+    }
+    if (channel.length > MAX_CHANNEL_LEN) {
+        throw new ValidationError(`[turbine] $listen/$notify channel "${channel}" exceeds the ${MAX_CHANNEL_LEN}-character Postgres identifier limit`);
+    }
+    if (!CHANNEL_REGEX.test(channel)) {
+        throw new ValidationError(`[turbine] Invalid $listen/$notify channel "${channel}" — must match /^[A-Za-z_][A-Za-z0-9_]*$/ ` +
+            '(letters, digits, underscores; cannot start with a digit)');
+    }
+}
+/**
+ * Acquire a dedicated connection, run `LISTEN "channel"`, and wire the handler.
+ *
+ * @param pool        the pg-compatible pool to check a long-lived client out of
+ * @param channel     channel name — MUST already be validated by the caller
+ * @param quotedChannel  the channel run through quoteIdent (interpolated into SQL)
+ * @param handler     called with each notification's payload
+ * @param onClosed    invoked when the subscription releases, so the client can
+ *                    drop it from its active-subscription registry
+ */
+export async function createSubscription(pool, channel, quotedChannel, handler, onClosed) {
+    let client;
+    try {
+        client = (await pool.connect());
+    }
+    catch (err) {
+        throw wrapPgError(err);
+    }
+    // Verify the checked-out client can actually receive async notifications.
+    // Stateless HTTP drivers return a client with no `.on` — LISTEN would hang
+    // forever waiting for messages that can never arrive, so fail loudly now and
+    // give the connection straight back.
+    if (typeof client.on !== 'function') {
+        client.release?.();
+        throw new ConnectionError('[turbine] $listen requires a persistent connection that can push notifications. ' +
+            'The configured pool returned a client with no event support (stateless HTTP drivers ' +
+            'like Neon HTTP / Vercel Postgres cannot LISTEN). Use a TCP pg.Pool for LISTEN/NOTIFY.');
+    }
+    const onNotification = (msg) => {
+        // pg delivers ALL notifications for the connection to every listener; a
+        // dedicated connection only ever LISTENs on one channel, but guard anyway.
+        if (msg.channel === channel) {
+            handler(msg.payload ?? '');
+        }
+    };
+    try {
+        client.on('notification', onNotification);
+        await client.query(`LISTEN ${quotedChannel}`);
+    }
+    catch (err) {
+        client.removeListener?.('notification', onNotification);
+        client.release?.();
+        throw wrapPgError(err);
+    }
+    let closed = false;
+    const sub = {
+        channel,
+        async unsubscribe() {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                await client.query(`UNLISTEN ${quotedChannel}`);
+            }
+            catch (err) {
+                // Best-effort: the connection may already be dead. Still detach +
+                // release below so we don't leak the pool slot.
+                client.removeListener?.('notification', onNotification);
+                client.release?.();
+                onClosed(sub);
+                throw wrapPgError(err);
+            }
+            client.removeListener?.('notification', onNotification);
+            client.release?.();
+            onClosed(sub);
+        },
+        _forceRelease() {
+            if (closed)
+                return;
+            closed = true;
+            client.removeListener?.('notification', onNotification);
+            // Destroy the connection (release(true)) rather than return it to the pool:
+            // we skip UNLISTEN here (the pool is being torn down), so a recycled
+            // connection would otherwise carry a stale LISTEN registration. Destroying
+            // it guarantees no pooled backend keeps receiving NOTIFY traffic. Matters
+            // most for external/serverless pools, where disconnect() is a no-op and the
+            // pool outlives this client.
+            client.release?.(true);
+            onClosed(sub);
+        },
+    };
+    return sub;
+}
+//# sourceMappingURL=realtime.js.map

package/dist/schema-builder.d.ts

@@ -22,6 +22,7 @@
  * });
  * ```
  */
+import type { SchemaMetadata } from './schema.js';
 /** Shorthand type names that map to Postgres column types */
 export type ColumnTypeName = 'serial' | 'bigint' | 'integer' | 'smallint' | 'text' | 'varchar' | 'boolean' | 'timestamp' | 'date' | 'json' | 'uuid' | 'real' | 'double' | 'numeric' | 'bytea';
 /** Column definition as a plain object. This is what users write. */
@@ -55,6 +56,36 @@ export interface ColumnConfig {
     referencesTarget: string | null;
     maxLength: number | null;
 }
+/**
+ * Explicit many-to-many relation declaration for the code-first schema.
+ *
+ * Auto-detecting m2m from a junction table is intentionally conservative (a
+ * junction with payload columns is treated as a first-class entity, not a join
+ * table — see `introspect.ts`). This declaration lets users opt in to an m2m
+ * relation explicitly, mirroring how Prisma/Drizzle require an explicit
+ * `@relation` / `relation()` for join tables.
+ *
+ * All names are the JS-facing accessor / camelCase field names you wrote in
+ * `defineSchema({ ... })`; they are normalized to snake_case when merged into
+ * the introspected {@link SchemaMetadata} via {@link applyManyToManyRelations}.
+ */
+export interface ManyToManyDef {
+    /** Relation field name on the source table (e.g. `tags`). */
+    name: string;
+    /** Target table accessor (e.g. `tags`). */
+    target: string;
+    /** Junction (join) table accessor (e.g. `postsTags`). */
+    through: string;
+    /** Junction column(s) referencing the SOURCE table's PK. */
+    sourceKey: string | readonly string[];
+    /** Junction column(s) referencing the TARGET table's PK. */
+    targetKey: string | readonly string[];
+    /**
+     * Optional: the SOURCE table's referenced column(s) that `sourceKey` points
+     * at. Defaults to `id`. Use for sources keyed on a non-`id` / composite PK.
+     */
+    references?: string | readonly string[];
+}
 export interface TableDef {
     /**
      * DDL-facing table name (snake_case). This is the name used when generating
@@ -79,6 +110,13 @@ export interface TableDef {
      * when emitted as a `PRIMARY KEY (...)` table constraint.
      */
     primaryKey?: readonly string[];
+    /**
+     * Explicit many-to-many relations declared on this table. These never affect
+     * DDL emission (junction tables are still ordinary `CREATE TABLE`s); they are
+     * consumed by {@link applyManyToManyRelations} to enrich an introspected
+     * {@link SchemaMetadata} with `manyToMany` {@link RelationDef}s.
+     */
+    manyToMany?: readonly ManyToManyDef[];
 }
 /**
  * User-facing input shape for a single table when using the object format.
@@ -87,8 +125,10 @@ export interface TableDef {
 export interface TableInput {
     /** Optional composite primary key (camelCase field names) */
     primaryKey?: readonly string[];
+    /** Optional explicit many-to-many relations on this table */
+    manyToMany?: readonly ManyToManyDef[];
     /** Column definitions keyed by camelCase field name */
-    [columnName: string]: ColumnDef | readonly string[] | undefined;
+    [columnName: string]: ColumnDef | readonly string[] | readonly ManyToManyDef[] | undefined;
 }
 export interface SchemaDef {
     /**
@@ -156,5 +196,32 @@ type ColumnProxy = {
 export declare const column: ColumnProxy;
 /** @deprecated Use defineSchema() with plain objects instead */
 export declare function table(columns: Record<string, ColumnBuilder>): TableDef;
+/**
+ * Merge the explicit `manyToMany` declarations from a code-first {@link SchemaDef}
+ * into an introspected {@link SchemaMetadata}, returning a new metadata object
+ * with the `manyToMany` {@link RelationDef}s added.
+ *
+ * This is the runtime bridge for the code-first m2m API: `defineSchema` only
+ * produces DDL, so after `introspect()`ing the live database you call this to
+ * attach the m2m relations you declared. It is PURELY ADDITIVE — existing
+ * belongsTo/hasMany/hasOne relations are preserved, and a declared relation is
+ * skipped (not overwritten) if its name already exists on the source table.
+ *
+ * @example
+ * ```ts
+ * const def = defineSchema({
+ *   posts: { id: { type: 'serial', primaryKey: true },
+ *            manyToMany: [{ name: 'tags', target: 'tags', through: 'postsTags',
+ *                           sourceKey: 'postId', targetKey: 'tagId' }] },
+ *   tags:  { id: { type: 'serial', primaryKey: true } },
+ *   postsTags: { postId: { type: 'integer', references: 'posts.id' },
+ *                tagId:  { type: 'integer', references: 'tags.id' },
+ *                primaryKey: ['postId', 'tagId'] },
+ * });
+ * let meta = await introspect({ connectionString });
+ * meta = applyManyToManyRelations(meta, def);
+ * ```
+ */
+export declare function applyManyToManyRelations(meta: SchemaMetadata, def: SchemaDef): SchemaMetadata;
 export { camelToSnake } from './schema.js';
 //# sourceMappingURL=schema-builder.d.ts.map

package/dist/schema-builder.js

@@ -97,7 +97,17 @@ export function defineSchema(input) {
             const raw = value;
             const columns = {};
             let pk;
+            let m2m;
             for (const [fieldName, def] of Object.entries(raw)) {
+                if (fieldName === 'manyToMany') {
+                    if (def !== undefined) {
+                        if (!Array.isArray(def)) {
+                            throw new Error(`Table "${accessor}": "manyToMany" must be an array of relation declarations`);
+                        }
+                        m2m = def;
+                    }
+                    continue;
+                }
                 if (fieldName === 'primaryKey') {
                     // Top-level composite primary key declaration
                     if (def !== undefined) {
@@ -137,6 +147,7 @@ export function defineSchema(input) {
                 accessor,
                 columns,
                 ...(pk && pk.length > 0 ? { primaryKey: pk } : {}),
+                ...(m2m && m2m.length > 0 ? { manyToMany: m2m } : {}),
             };
         }
     }
@@ -297,6 +308,80 @@ export function table(columns) {
     return { name: '', accessor: '', columns: built };
 }
 // ---------------------------------------------------------------------------
+// Explicit many-to-many: merge declared relations into introspected metadata
+// ---------------------------------------------------------------------------
+/**
+ * Merge the explicit `manyToMany` declarations from a code-first {@link SchemaDef}
+ * into an introspected {@link SchemaMetadata}, returning a new metadata object
+ * with the `manyToMany` {@link RelationDef}s added.
+ *
+ * This is the runtime bridge for the code-first m2m API: `defineSchema` only
+ * produces DDL, so after `introspect()`ing the live database you call this to
+ * attach the m2m relations you declared. It is PURELY ADDITIVE — existing
+ * belongsTo/hasMany/hasOne relations are preserved, and a declared relation is
+ * skipped (not overwritten) if its name already exists on the source table.
+ *
+ * @example
+ * ```ts
+ * const def = defineSchema({
+ *   posts: { id: { type: 'serial', primaryKey: true },
+ *            manyToMany: [{ name: 'tags', target: 'tags', through: 'postsTags',
+ *                           sourceKey: 'postId', targetKey: 'tagId' }] },
+ *   tags:  { id: { type: 'serial', primaryKey: true } },
+ *   postsTags: { postId: { type: 'integer', references: 'posts.id' },
+ *                tagId:  { type: 'integer', references: 'tags.id' },
+ *                primaryKey: ['postId', 'tagId'] },
+ * });
+ * let meta = await introspect({ connectionString });
+ * meta = applyManyToManyRelations(meta, def);
+ * ```
+ */
+export function applyManyToManyRelations(meta, def) {
+    // Map accessor (camelCase key) → DDL snake_case table name.
+    const accessorToTable = new Map();
+    for (const [accessor, t] of Object.entries(def.tables)) {
+        accessorToTable.set(accessor, t.name);
+    }
+    const resolveTable = (accessor) => accessorToTable.get(accessor) ?? camelToSnakeLocal(accessor);
+    const resolveCols = (k) => {
+        if (Array.isArray(k))
+            return k.map(camelToSnakeLocal);
+        return camelToSnakeLocal(k);
+    };
+    // Deep-ish clone of the tables we touch so the input metadata is not mutated.
+    const tables = { ...meta.tables };
+    for (const tableDef of Object.values(def.tables)) {
+        if (!tableDef.manyToMany || tableDef.manyToMany.length === 0)
+            continue;
+        const sourceTable = tableDef.name;
+        const sourceMeta = tables[sourceTable];
+        if (!sourceMeta)
+            continue; // table not present in introspected metadata — skip
+        const relations = { ...sourceMeta.relations };
+        for (const m of tableDef.manyToMany) {
+            // Additive-only: never clobber an existing relation name.
+            if (relations[m.name])
+                continue;
+            const ref = m.references ?? 'id';
+            relations[m.name] = {
+                type: 'manyToMany',
+                name: m.name,
+                from: sourceTable,
+                to: resolveTable(m.target),
+                referenceKey: resolveCols(ref),
+                foreignKey: resolveCols(ref),
+                through: {
+                    table: resolveTable(m.through),
+                    sourceKey: resolveCols(m.sourceKey),
+                    targetKey: resolveCols(m.targetKey),
+                },
+            };
+        }
+        tables[sourceTable] = { ...sourceMeta, relations };
+    }
+    return { ...meta, tables };
+}
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 export { camelToSnake } from './schema.js';

package/dist/schema.d.ts

@@ -61,7 +61,7 @@ export interface ColumnMetadata {
     maxLength?: number;
 }
 export interface RelationDef {
-    type: 'hasMany' | 'hasOne' | 'belongsTo';
+    type: 'hasMany' | 'hasOne' | 'belongsTo' | 'manyToMany';
     /** Relation name (camelCase, used as the field name) */
     name: string;
     /** Source table */
@@ -72,6 +72,23 @@ export interface RelationDef {
     foreignKey: string | string[];
     /** Referenced column(s) on the "one" / "parent" side (snake_case). Array for composite FKs. */
     referenceKey: string | string[];
+    /**
+     * For `manyToMany` relations only: the junction (join) table that links the
+     * source and target tables. The subquery JOINs the target through this table.
+     *
+     *   - `table`     — junction table name (snake_case).
+     *   - `sourceKey` — junction column(s) referencing the SOURCE table's
+     *                   {@link referenceKey} (typically the source PK).
+     *   - `targetKey` — junction column(s) referencing the TARGET table's PK.
+     *
+     * Array forms support composite keys (paired positionally with the
+     * referenced columns). Omitted for non-m2m relations.
+     */
+    through?: {
+        table: string;
+        sourceKey: string | string[];
+        targetKey: string | string[];
+    };
 }
 /** Normalize foreignKey/referenceKey to always be an array for uniform processing */
 export declare function normalizeKeyColumns(key: string | string[]): string[];

package/dist/schema.js

@@ -66,6 +66,16 @@ const PG_TO_TS = {
     // TSVector
     tsvector: 'string',
     tsquery: 'string',
+    // pgvector — embeddings. Mapped to `number[]` for DX (the natural shape an app
+    // passes when inserting / comparing embeddings). NOTE: like `numeric` above,
+    // there is a runtime caveat — pg has no built-in parser for the `vector` type,
+    // so over the wire a fetched vector arrives as a string literal like
+    // '[1,2,3]' unless the app registers its own parser (e.g. via pgvector's
+    // `registerType`). Turbine never auto-registers one (no side-effecting type
+    // parsers outside the client constructor). The query-side helpers (KNN
+    // orderBy, distance WHERE) always bind the query vector as a `$n::vector`
+    // param, so writing/comparing is unaffected by the read-side caveat.
+    vector: 'number[]',
 };
 const DATE_TYPES = new Set(['timestamptz', 'timestamp', 'date']);
 const PG_TO_ARRAY = {