turbine-orm 0.49.0 → 0.50.0

package/dist/cjs/index-advisor.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Index advisor — finds relation probes that lack index support.
+ *
+ * Turbine loads `with` relations as correlated subqueries: for every parent row,
+ * the child table is probed by its FK column(s) (`child.fk = parent.pk`). Relation
+ * filters (`some`/`none`/`every`, `is`/`isNot`) probe the same columns. This
+ * strategy outperforms batched loading (`WHERE fk IN (ids)`) when the probed
+ * column is indexed — but with NO index, each probe is a full table scan and the
+ * cost multiplies by the parent rowcount, while batched loading would pay the
+ * scan only once. A missing FK index that is invisible under a batched-loader
+ * ORM becomes pathological under a correlated one.
+ *
+ * This module derives every column set Turbine will probe from SchemaMetadata's
+ * relations and checks each against the table's known indexes (and primary key).
+ * Consumed by `turbine doctor` (CLI report + fix migration) and by the dev-mode
+ * runtime warning in query/builder.ts.
+ */
+import { type SchemaMetadata, type TableMetadata } from './schema.js';
+export interface RelationProbe {
+    /** Table on which the relation is declared */
+    from: string;
+    /** Relation field name */
+    relation: string;
+    /** Relation type */
+    type: 'hasMany' | 'hasOne' | 'belongsTo' | 'manyToMany';
+}
+export interface MissingRelationIndex {
+    /** Table that gets probed per parent row */
+    table: string;
+    /** Probed column(s) — equality lookups, so a covering index must LEAD with one of them */
+    columns: string[];
+    /** Every relation that generates this probe */
+    probes: RelationProbe[];
+    /** Suggested index name (matches the --fix migration) */
+    indexName: string;
+    /** CREATE INDEX statement for the fix migration */
+    createSql: string;
+    /** DROP INDEX statement for the fix migration's DOWN section */
+    dropSql: string;
+}
+/** Options for {@link buildCreateIndexSql}. All default to the plain, in-transaction form. */
+export interface CreateIndexSqlOptions {
+    /**
+     * Emit `CREATE INDEX CONCURRENTLY`. A concurrent build never holds a write
+     * lock, but it CANNOT run inside a transaction block, so a migration carrying
+     * it must also carry the `-- turbine:no-transaction` directive.
+     */
+    concurrently?: boolean;
+    /** Emit `IF NOT EXISTS` (default true — required for idempotent no-transaction migrations). */
+    ifNotExists?: boolean;
+    /**
+     * Emit a partial index `... WHERE <col> IS NOT NULL`. Only applied for a
+     * single-column index (a relation probe correlates `child.fk = parent.pk`, and
+     * NULL never equals anything, so a mostly-NULL FK is fully served by a partial
+     * index at a fraction of the size). Ignored for composite indexes.
+     */
+    partialNotNull?: boolean;
+}
+/**
+ * Build a `CREATE INDEX` statement for a relation-probe fix. Pure string
+ * assembly (no stats, no DB read): the caller decides whether to pass
+ * `concurrently`/`partialNotNull` based on collected statistics, keeping this
+ * module topology-only.
+ */
+export declare function buildCreateIndexSql(table: string, columns: string[], indexName: string, options?: CreateIndexSqlOptions): string;
+/** Build the matching `DROP INDEX` statement. `concurrently` requires no-transaction execution. */
+export declare function buildDropIndexSql(indexName: string, options?: {
+    concurrently?: boolean;
+    ifExists?: boolean;
+}): string;
+/**
+ * Whether an equality probe on `columns` is served by the table's indexes.
+ *
+ * All probe columns are equality predicates, so any index whose FIRST column is
+ * one of the probed columns gives the planner an index path (a btree can't use
+ * a column that isn't in its leading prefix). This is deliberately the loose
+ * direction: it never flags a table that has *any* usable index for the probe,
+ * at the cost of not demanding the ideal multi-column index. The primary key
+ * counts as an index.
+ */
+export declare function isProbeIndexed(meta: TableMetadata, columns: string[]): boolean;
+/**
+ * The deterministic index name `doctor --fix` uses for a relation-probe index:
+ * `idx_<table>_<cols>` truncated to Postgres's 63-byte identifier limit. `doctor
+ * --audit` recomputes this to recognize its own previously-suggested indexes.
+ */
+export declare function doctorIndexName(table: string, columns: string[]): string;
+/** A (table, columns) pair whose probe maps to a given deterministic name. */
+export interface DoctorProbeColumns {
+    table: string;
+    columns: string[];
+}
+/**
+ * Map every deterministic doctor index name the schema's relation probes would
+ * generate to the distinct column sets that produce it. A name that maps to more
+ * than one distinct column set is a post-truncation collision (very long column
+ * names slicing to the same 63 bytes): `doctor --audit` reports those as
+ * ambiguous rather than issuing a confident drop verdict.
+ */
+export declare function collectDoctorProbeIndexNames(schema: SchemaMetadata): Map<string, DoctorProbeColumns[]>;
+/**
+ * Every (table, column set) a relation probe touches, deduplicated. Consumed by
+ * the subtraction side of `doctor` so an index that still serves a live relation
+ * is never handed a DROP: the same run's top half demands that index, and
+ * recommending both in one report is how a tool loses a DBA's trust.
+ */
+export declare function collectRelationProbeColumns(schema: SchemaMetadata): DoctorProbeColumns[];
+/**
+ * Scan every relation in the schema and return the probes with no index support,
+ * deduplicated by (table, column set) with all contributing relations attached.
+ *
+ * Only meaningful when the metadata carries index information (i.e. it came from
+ * introspection or a generated client). Callers that may hold index-less metadata
+ * should gate on {@link schemaHasIndexInfo} to avoid blanket false positives.
+ */
+export declare function findMissingRelationIndexes(schema: SchemaMetadata): MissingRelationIndex[];
+/**
+ * True when at least one table in the schema carries real, DB-backed index
+ * metadata (i.e. from introspection).
+ *
+ * Excluded (so they never flip the flag, keeping the schema "index-info
+ * unknown"):
+ *   - doc-field expression indexes (`docPath`): they carry no FK-coverage info;
+ *   - code-first DECLARED indexes (`declared`): the SQL DDL generators do NOT
+ *     emit `TableDef.indexes` yet, so a declared index does not reflect a real
+ *     index on the SQL engines. Counting one would arm blanket FK false
+ *     positives (the FK auto-index the push path DID create is then reported
+ *     "missing") and, inversely, suppress warnings for indexes never created.
+ *     A pure code-first schema therefore stays silent exactly as it did before
+ *     `TableDef.indexes` existed.
+ */
+export declare function schemaHasIndexInfo(schema: SchemaMetadata): boolean;
+/**
+ * Single-relation check for the dev-mode runtime warning: the (table, columns)
+ * this relation probes and whether that probe is unindexed. Returns null when
+ * indexed, unknown, or when the schema carries no index info at all (metadata
+ * built without introspection — warning would be a blanket false positive).
+ */
+export declare function missingIndexForRelation(schema: SchemaMetadata, relDef: {
+    name: string;
+    type: RelationProbe['type'];
+    to: string;
+    foreignKey: string | string[];
+    referenceKey: string | string[];
+    through?: {
+        table: string;
+        sourceKey: string | string[];
+    };
+}): {
+    table: string;
+    columns: string[];
+    createSql: string;
+} | null;

package/dist/cjs/index-stats.d.ts

@@ -0,0 +1,384 @@
+/**
+ * Index statistics - cost-aware triage for the missing-index advisor.
+ *
+ * `index-advisor.ts` decides WHICH relation probes lack an index from pure
+ * schema topology. This module decides whether adding each one is worth it,
+ * reading live Postgres statistics (table size, write volume, existing indexes,
+ * HOT-update ratio, column null fraction) and scoring every finding into a tier:
+ *
+ *   - take-freely       large table, low write rate, few existing indexes;
+ *   - take-deliberately real write rate, many existing indexes, or HOT at risk;
+ *   - scrutinize        tiny table, append-only log shape, or stats too young.
+ *
+ * DESIGN: the file splits into two halves.
+ *   - The COLLECTOR half (`collectStatsSnapshot`) reads pg catalogs. It uses a
+ *     single one-connection pool, sets a statement_timeout, and treats every
+ *     catalog read as INDIVIDUALLY OPTIONAL: a read that fails (privileges,
+ *     CockroachDB/YugabyteDB catalog gaps, missing view) degrades that one
+ *     signal and records a notice rather than aborting the whole snapshot.
+ *   - The PURE half (`scoreMissingIndex`, `findInvalidIndexes`, and the exported
+ *     threshold constants) takes a typed {@link StatsSnapshot} and imports NO pg.
+ *     It is fully unit-testable with hand-built snapshots and is what carries the
+ *     thresholds the CLI prints alongside every verdict.
+ *
+ * All statistics features are Postgres-only. On a non-Postgres engine the
+ * collector returns an unavailable snapshot and the caller falls back to the
+ * topology-only report.
+ */
+/**
+ * Heuristic thresholds behind the tier decision. Exported and surfaced in the
+ * doctor output so the reasoning is never a black box: if a threshold is wrong
+ * for a workload, the user can see the exact number that drove the verdict.
+ */
+export declare const STATS_THRESHOLDS: {
+    /** reltuples below this = tiny table; a missing index there is noise → scrutinize. */
+    readonly tinyTableRows: 1000;
+    /**
+     * Writes/day (n_tup_ins+upd+del normalized by stats age) at or above this is a
+     * "real" write rate: the per-index write tax is worth a second look → take deliberately.
+     */
+    readonly highWritesPerDay: 50000;
+    /**
+     * Existing index count at or above this: every extra index compounds the write
+     * and storage tax, so a new one is no longer free → take deliberately.
+     */
+    readonly manyIndexes: 4;
+    /**
+     * HOT ratio (n_tup_hot_upd / n_tup_upd) at or above this, WITH real update
+     * volume, means the table currently relies on heap-only-tuple updates. A new
+     * index can disqualify HOT and amplify write cost → warning + take deliberately.
+     */
+    readonly hotRatioAtRisk: 0.3;
+    /** Minimum n_tup_upd for the HOT signal to be statistically meaningful. */
+    readonly hotMinUpdates: 1000;
+    /**
+     * null_frac at or above this on a probed FK column: the column is mostly NULL,
+     * so a partial `WHERE col IS NOT NULL` index covers every relation probe at a
+     * fraction of the size.
+     */
+    readonly partialNullFrac: 0.9;
+    /**
+     * Stats younger than this (days since stats_reset) cannot normalize a write
+     * rate; the whole report degrades to topology-only output.
+     */
+    readonly minStatsAgeDays: 1;
+    /** Append-heavy log shape: n_tup_ins at or above this ... */
+    readonly appendHeavyMinInserts: 100000;
+    /** ... with inserts making up at or above this fraction of all writes ... */
+    readonly appendHeavyInsertRatio: 0.95;
+    /** ... and seq_scan at or below this ("near-zero probe reads") → scrutinize. */
+    readonly appendHeavyMaxSeqScan: 5;
+    /**
+     * Default `--min-scans` for the unused-index report: an index with fewer than
+     * this many scans since stats_reset is flagged never-scanned. Default 1 makes
+     * the bare report mean exactly "idx_scan = 0".
+     */
+    readonly unusedMinScans: 1;
+    /**
+     * Queries/min (from _turbine_metrics) at or above this makes a table "hot in
+     * your workload": a benefit signal that boosts the finding's priority and
+     * annotates it. It never downgrades a cost tier (write cost is a separate axis).
+     */
+    readonly heatMinQueriesPerMin: 1;
+};
+/** Per-table live statistics. Any field may be absent when its catalog read degraded. */
+export interface TableStats {
+    table: string;
+    /** pg_class.reltuples. 0 or -1 means never-analyzed → treated as UNKNOWN (null rows). */
+    reltuples: number;
+    /** pg_stat_user_tables.n_live_tup, a cross-check for reltuples. */
+    nLiveTup?: number;
+    nTupIns?: number;
+    nTupUpd?: number;
+    nTupDel?: number;
+    nTupHotUpd?: number;
+    seqScan?: number;
+    seqTupRead?: number;
+    /** pg_total_relation_size (table + indexes + toast), bytes. */
+    totalSizeBytes?: number;
+    /** pg_relation_size (heap only), bytes. */
+    tableSizeBytes?: number;
+    /** Count of indexes already on the table (pg_index). */
+    existingIndexCount?: number;
+}
+/**
+ * Placeholder for an index column that is an EXPRESSION, not a plain column
+ * (`pg_index.indkey` stores 0 for those, and no `pg_attribute` row has attnum 0).
+ * It keeps expression POSITIONS in `IndexStat.columns` instead of silently
+ * collapsing `(tenant_id, lower(email))` to `['tenant_id']`, which would make a
+ * functional index look like a droppable prefix of an unrelated plain index.
+ */
+export declare const EXPRESSION_COLUMN = "(expression)";
+/** A single index's identity + validity, from pg_index / pg_stat_user_indexes. */
+export interface IndexStat {
+    table: string;
+    indexName: string;
+    /** Key + INCLUDE columns in order; an expression slot is {@link EXPRESSION_COLUMN}. */
+    columns: string[];
+    /** pg_am.amname (btree / gin / gist / hash / brin / spgist). Absent when unread. */
+    accessMethod?: string;
+    /** True when the index has at least one expression column (pg_index.indexprs). */
+    hasExpressions?: boolean;
+    /** The partial-index predicate text (pg_index.indpred), or null when not partial. */
+    predicate?: string | null;
+    /** pg_get_indexdef, the authoritative definition (used for honest reporting). */
+    indexDef?: string;
+    idxScan?: number;
+    isValid: boolean;
+    isUnique: boolean;
+    isPrimary: boolean;
+    isReplicaIdent: boolean;
+    /** Backs an exclusion constraint (pg_constraint.contype = 'x'). */
+    isExclusion?: boolean;
+    /** pg_relation_size of the index heap, bytes. Size reclaimed by a drop. */
+    sizeBytes?: number;
+}
+/**
+ * A point-in-time read of the statistics the triage needs. Every part is
+ * optional at the field level so the pure scorer degrades honestly.
+ */
+export interface StatsSnapshot {
+    /** True when at least the core table statistics were readable. */
+    available: boolean;
+    /** pg_stat_database.stats_reset for the current DB. NULL when never reset. */
+    statsReset: Date | null;
+    /** Days since stats_reset, or null when stats_reset is NULL / in the future. */
+    statsAgeDays: number | null;
+    /** Per-table stats, keyed by table name. */
+    tables: Record<string, TableStats>;
+    /** All indexes read (used for invalid-index detection). */
+    indexes: IndexStat[];
+    /** null_frac per probed column, keyed `table.column`. */
+    nullFrac: Record<string, number>;
+    /** Per-signal degradation notices (privileges, catalog gaps, timeouts). */
+    notices: string[];
+}
+/** Build an empty (fully unavailable) snapshot - the honest "no stats" baseline. */
+export declare function emptyStatsSnapshot(notices?: string[]): StatsSnapshot;
+export type IndexTier = 'take-freely' | 'take-deliberately' | 'scrutinize';
+/** The numbers behind a verdict, all nullable so unknowns never masquerade as zero. */
+export interface FindingMetrics {
+    /** reltuples, or null when never-analyzed (0/-1). */
+    rows: number | null;
+    /** pg_total_relation_size in bytes. */
+    sizeBytes: number | null;
+    /** Writes/day since stats reset, or null when the rate cannot be normalized. */
+    writesPerDay: number | null;
+    existingIndexCount: number | null;
+    probingRelations: number;
+    /** n_tup_hot_upd / n_tup_upd, or null. */
+    hotRatio: number | null;
+    /** Highest null_frac across the probed columns, or null when unknown. */
+    nullFrac: number | null;
+    statsAgeDays: number | null;
+}
+export interface ScoredMissingIndex {
+    table: string;
+    columns: string[];
+    tier: IndexTier;
+    /** Human-readable reasons, each carrying the number that drove it. */
+    reasons: string[];
+    metrics: FindingMetrics;
+    /** The HOT-update caveat when the table is at risk of losing HOT, else null. */
+    hotWarning: string | null;
+    /** When true, the emitted index should be a partial `WHERE col IS NOT NULL`. */
+    partialNotNull: boolean;
+    /** True when workload heat lifted this finding's priority (see {@link TableHeatEntry}). */
+    heatBoosted: boolean;
+    /** Sort key within a tier: bigger, more-probed tables first; hot tables first of all. */
+    benefitScore: number;
+}
+/** Per-table workload heat, derived from the _turbine_metrics per-minute aggregates. */
+export interface TableHeatEntry {
+    /** Average queries per minute across the observed window. */
+    queriesPerMin: number;
+    /** Worst observed p95 latency (ms) across the window. */
+    p95Ms: number;
+}
+/** The subset of a topology finding the scorer needs. */
+export interface ScorableMissingIndex {
+    table: string;
+    columns: string[];
+    probes: unknown[];
+}
+/** Format a byte count as a short human string (KB/MB/GB). */
+export declare function formatBytes(bytes: number | null | undefined): string;
+/**
+ * Score a single missing-index finding against a snapshot. Pure and total:
+ * every unknown degrades to a caveat rather than a fabricated number.
+ */
+export declare function scoreMissingIndex(missing: ScorableMissingIndex, snapshot: StatsSnapshot, heat?: TableHeatEntry): ScoredMissingIndex;
+export interface InvalidIndex {
+    table: string;
+    indexName: string;
+    columns: string[];
+    /** `DROP INDEX CONCURRENTLY IF EXISTS` - the repair for an INVALID corpse. */
+    dropSql: string;
+}
+/**
+ * Indexes left INVALID (indisvalid = false) - the failure artifact of a
+ * `CREATE INDEX CONCURRENTLY` that errored. `IF NOT EXISTS` on a retry silently
+ * skips the corpse, so the fix is DROP INDEX CONCURRENTLY then rerun.
+ */
+export declare function findInvalidIndexes(snapshot: StatsSnapshot): InvalidIndex[];
+/** A never-scanned index and the DROP statement that would reclaim it. */
+export interface UnusedIndex {
+    table: string;
+    indexName: string;
+    columns: string[];
+    /** idx_scan since the last stats reset (0 or below --min-scans). */
+    idxScan: number;
+    /** Size reclaimed by the drop, bytes (null when the size read degraded). */
+    sizeBytes: number | null;
+    /** `DROP INDEX CONCURRENTLY IF EXISTS`: printed only, never written to a migration. */
+    dropSql: string;
+    /**
+     * What is special about this index (functional / partial / non-btree), or null
+     * for a plain btree. `idx_scan = 0` is a fact either way, but the caveat says
+     * what is actually being dropped: a rebuild is not always a `CREATE INDEX (col)`.
+     */
+    caveat: string | null;
+    /**
+     * The same information as `caveat`, structured, so a `--json` consumer never
+     * has to regex prose. `kinds` is empty for a plain btree index.
+     */
+    shape: {
+        kinds: Array<'expression' | 'partial' | 'non-btree'>;
+        accessMethod: string | null;
+        definition: string | null;
+    };
+}
+/**
+ * Indexes never (or barely) scanned since the last stats reset. Report-only:
+ * counters reset on a crash/reset and REPLICA READS NEVER FEED PRIMARY COUNTERS,
+ * so an index only a read replica uses looks dead here. Constraint-backing and
+ * replica-identity indexes are excluded by construction. An index whose idx_scan
+ * could not be read (no pg_stat row) is skipped rather than guessed.
+ */
+export declare function findUnusedIndexes(snapshot: StatsSnapshot, options?: {
+    minScans?: number;
+    relationProbes?: Array<{
+        table: string;
+        columns: string[];
+    }>;
+}): UnusedIndex[];
+/** A redundant index whose columns are a leading prefix of a wider index. */
+export interface RedundantIndex {
+    table: string;
+    indexName: string;
+    columns: string[];
+    /** The wider index that already covers this one's leading-prefix lookups. */
+    coveredBy: string;
+    coveredByColumns: string[];
+    sizeBytes: number | null;
+    dropSql: string;
+}
+/**
+ * Non-unique indexes whose column list is a leading prefix of a WIDER index on
+ * the same table. A btree serves any leading-prefix lookup, so the narrow index
+ * is redundant. Pure metadata (no idx_scan needed).
+ *
+ * Uniqueness compatibility: only a NON-unique index is ever reported. A unique
+ * or primary-key prefix is load-bearing (it enforces a constraint), so it is
+ * never called redundant even when a wider index shares its leading columns.
+ *
+ * Shape compatibility: see {@link isCoverageComparable}. A functional, partial,
+ * or non-btree index is never reported as covered by a plain btree.
+ */
+export declare function findRedundantIndexes(snapshot: StatsSnapshot): RedundantIndex[];
+/**
+ * A `doctor --audit` finding: an existing index that matches doctor's own
+ * deterministic naming AND has not been scanned since the stats reset.
+ */
+export interface DoctorIndexAudit {
+    table: string;
+    indexName: string;
+    columns: string[];
+    idxScan: number;
+    sizeBytes: number | null;
+    /** `null` when the index still serves a live relation probe (see stillProbed). */
+    dropSql: string | null;
+    /**
+     * True when the truncated (63-byte) name collides across DIFFERENT column sets
+     * in the schema's probes, so which suggestion this index realizes is
+     * ambiguous. Reported as ambiguous instead of a confident drop verdict.
+     */
+    ambiguous: boolean;
+    /**
+     * True when the schema still declares a relation whose probe this index
+     * serves. `dropSql` is null in that case: the index is unused only because
+     * this workload has not run those relation queries yet, and dropping it
+     * recreates the missing-index finding in the same report's top half.
+     */
+    stillProbed: boolean;
+}
+/**
+ * The unused-index machinery scoped to doctor's OWN previously-suggested indexes:
+ * existing indexes whose name matches the `idx_<table>_<cols>` (63-byte truncated)
+ * shape doctor emits, never scanned since the stats reset. `doctorNames` maps each
+ * deterministic name to the distinct column sets that truncate to it (see
+ * `collectDoctorProbeIndexNames`); a name with more than one column set is a
+ * post-truncation collision, reported as ambiguous.
+ */
+export declare function auditDoctorIndexes(snapshot: StatsSnapshot, doctorNames: Map<string, Array<{
+    table: string;
+    columns: string[];
+}>>, options?: {
+    minScans?: number;
+    relationProbes?: Array<{
+        table: string;
+        columns: string[];
+    }>;
+}): DoctorIndexAudit[];
+/**
+ * Whether the snapshot is trustworthy enough to render tier verdicts. Empty,
+ * unavailable, or too-young stats degrade to the topology-only report.
+ */
+export declare function isSnapshotUsable(snapshot: StatsSnapshot): boolean;
+/** A tuple identifying a probed column whose null_frac the collector should read. */
+export interface ProbedColumn {
+    table: string;
+    column: string;
+}
+export interface CollectSnapshotOptions {
+    connectionString: string;
+    schema: string;
+    /** Tables to read table-level stats + sizes for (the probed tables). */
+    tables: string[];
+    /** Columns to read null_frac for (single-column probes). */
+    columns: ProbedColumn[];
+    /** statement_timeout for each catalog read. Default 5000ms. */
+    statementTimeoutMs?: number;
+}
+/**
+ * Read a live statistics snapshot from Postgres. Each catalog read is wrapped
+ * individually: a failure records a notice and leaves that signal absent, so a
+ * privilege gap or a CockroachDB/YugabyteDB catalog difference degrades one
+ * signal rather than the whole snapshot.
+ */
+export declare function collectStatsSnapshot(options: CollectSnapshotOptions): Promise<StatsSnapshot>;
+export interface CollectTableHeatOptions {
+    /** Where _turbine_metrics lives (the app DB, or a separate --metrics-url DB). */
+    connectionString: string;
+    /** Model names to read heat for (the probed table names). */
+    models: string[];
+    /** Trailing window of per-minute buckets to average, minutes. Default 60. */
+    windowMinutes?: number;
+    statementTimeoutMs?: number;
+}
+export interface TableHeatResult {
+    /** True when _turbine_metrics existed and was read. False = heat boosting off. */
+    available: boolean;
+    /** Per-model heat, keyed by model (= table) name. */
+    tables: Record<string, TableHeatEntry>;
+    /** One honesty line when heat could not be sourced (absent table / non-pg sink). */
+    notice: string | null;
+}
+/**
+ * Read per-model workload heat from a `_turbine_metrics` table (written by
+ * `db.$observe()` with the default Postgres sink). When the table is absent, the
+ * result is `available: false` with a notice: this is the expected state when
+ * observe uses a non-Postgres sink, or when no metrics have been collected yet.
+ * Every read is best-effort; a failure degrades to unavailable, never throws.
+ */
+export declare function collectTableHeat(options: CollectTableHeatOptions): Promise<TableHeatResult>;

package/dist/cjs/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * turbine-orm
+ *
+ * Turbine TypeScript SDK — type-safe Postgres queries with nested relations
+ * and pipeline batching. Feels like Prisma, runs at raw-SQL speed.
+ *
+ * @example
+ * ```ts
+ * // 1. Generate types from your database:
+ * //    npx turbine generate
+ *
+ * // 2. Import the generated client:
+ * import { turbine } from './generated/turbine';
+ *
+ * const db = turbine({ connectionString: process.env.DATABASE_URL });
+ *
+ * // Type-safe queries with auto-complete
+ * const user = await db.users.findUnique({ where: { id: 1 } });
+ *
+ * // Nested relations in a single query (json_agg, no N+1)
+ * const userWithPosts = await db.users.findUnique({
+ *   where: { id: 1 },
+ *   with: { posts: { with: { comments: true } } },
+ * });
+ *
+ * // Pipeline: multiple queries in one round-trip
+ * const [user, count] = await db.pipeline(
+ *   db.users.buildFindUnique({ where: { id: 1 } }),
+ *   db.posts.buildCount({ where: { orgId: 1 } }),
+ * );
+ *
+ * await db.disconnect();
+ * ```
+ */
+export type { DatabaseAdapter, IntrospectionOverrides } from './adapters/index.js';
+export { alloydb, cockroachdb, postgresql, timescale, yugabytedb } from './adapters/index.js';
+export { type Middleware, type MiddlewareNext, type MiddlewareParams, type PgCompatPool, type PgCompatPoolClient, type PgCompatQueryResult, type RetryOptions, TransactionClient, type TransactionOptions, TurbineClient, type TurbineConfig, type TurbineDriver, withRetry, } from './client.js';
+export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, DialectIntrospector, DialectMigrator, DialectName, InsertStatementInput, IntrospectOptions as DialectIntrospectOptions, ResultStrategy, StreamableConnection, UpsertStatementInput, } from './dialect.js';
+export { postgresDialect } from './dialect.js';
+export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockError, type ErrorMessageMode, ExclusionConstraintError, ForeignKeyError, getErrorMessageMode, MigrationError, NotFoundError, NotNullViolationError, OptimisticLockError, PipelineError, type PipelineResultSlot, ReadOnlyError, RelationError, SerializationFailureError, setErrorMessageMode, TimeoutError, TurbineError, TurbineErrorCode, UniqueConstraintError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
+export { type GenerateOptions, generate } from './generate.js';
+export { type IntrospectOptions, introspect } from './introspect.js';
+export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
+export { HttpJsonSink, type HttpJsonSinkOptions, type MetricsFlushBatch, type MetricsFlushRow, type ObserveConfig, type ObserveHandle, type ObserveSink, PgMetricsSink, type PgMetricsSinkOptions, } from './observe.js';
+export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
+export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
+export type { CheckMetadata, ColumnMetadata, IndexMetadata, PrismaCompatMap, PrismaModelMap, PrismaRelationMap, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
+export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, withDbFieldNames, } from './schema.js';
+export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnIndexDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, type DocFieldIndexDef, defineSchema, isDocFieldIndexDef, type ManyToManyDef, type ReferenceDef, type SchemaDef, type SchemaIndexDef, type TableDef, table, } from './schema-builder.js';
+export { schemaDefToMetadata } from './schema-metadata.js';
+export { type AlterColumnDef, type AlterDef, DestructivePushRefusal, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
+export { type DefinedSeed, defineSeed, type SeedFunction } from './seed.js';
+export { type TurbineHttpOptions, turbineHttp } from './serverless.js';
+export { buildTypedSql, TypedSqlQuery } from './typed-sql.js';

package/dist/cjs/index.js

@@ -34,8 +34,8 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.PgMetricsSink = exports.HttpJsonSink = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.ReadOnlyError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
-exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.DestructivePushRefusal = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.withDbFieldNames = exports.snakeToPascal = void 0;
+exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.AUTO_TO_ONE_JOIN_ROWS_MIN = exports.AUTO_TO_ONE_JOIN_ROWS_MAX = exports.AUTO_TO_ONE_JOIN_MAX_ROWS = exports.AUTO_JOIN_PENALTY_MS_PER_ROW = exports.AUTO_ASSUMED_ROUND_TRIP_MS = exports.pipelineSupported = exports.executePipeline = exports.PgMetricsSink = exports.HttpJsonSink = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.ReadOnlyError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
+exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.DestructivePushRefusal = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.withDbFieldNames = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = void 0;
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "alloydb", { enumerable: true, get: function () { return index_js_1.alloydb; } });
 Object.defineProperty(exports, "cockroachdb", { enumerable: true, get: function () { return index_js_1.cockroachdb; } });
@@ -95,6 +95,11 @@ Object.defineProperty(exports, "executePipeline", { enumerable: true, get: funct
 Object.defineProperty(exports, "pipelineSupported", { enumerable: true, get: function () { return pipeline_js_1.pipelineSupported; } });
 // Query builder
 var index_js_2 = require("./query/index.js");
+Object.defineProperty(exports, "AUTO_ASSUMED_ROUND_TRIP_MS", { enumerable: true, get: function () { return index_js_2.AUTO_ASSUMED_ROUND_TRIP_MS; } });
+Object.defineProperty(exports, "AUTO_JOIN_PENALTY_MS_PER_ROW", { enumerable: true, get: function () { return index_js_2.AUTO_JOIN_PENALTY_MS_PER_ROW; } });
+Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_MAX_ROWS", { enumerable: true, get: function () { return index_js_2.AUTO_TO_ONE_JOIN_MAX_ROWS; } });
+Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_ROWS_MAX", { enumerable: true, get: function () { return index_js_2.AUTO_TO_ONE_JOIN_ROWS_MAX; } });
+Object.defineProperty(exports, "AUTO_TO_ONE_JOIN_ROWS_MIN", { enumerable: true, get: function () { return index_js_2.AUTO_TO_ONE_JOIN_ROWS_MIN; } });
 Object.defineProperty(exports, "QueryInterface", { enumerable: true, get: function () { return index_js_2.QueryInterface; } });
 // Realtime — LISTEN/NOTIFY pub/sub
 var realtime_js_1 = require("./realtime.js");