turbine-orm 0.48.0 → 0.49.0

package/dist/cli/studio.d.ts

@@ -68,10 +68,26 @@ export interface StudioOptions {
      * three-mode switcher (`/api/demo/mode`). Default `false`.
      */
     demo?: boolean;
+    /**
+     * Directory holding generated Turbine metadata (`turbine generate`'s `out`).
+     * PII tags are code-first declarations that introspection never sets, so
+     * without this Studio's redaction has nothing to redact against a real
+     * database. Read as text; nothing from it is executed. See `pii-tags.ts`.
+     */
+    metadataDir?: string;
 }
 export interface StudioHandle {
     /** Shut down the server + pool cleanly. */
     dispose: () => Promise<void>;
+    /**
+     * Where PII tags came from, so the CLI can say so at startup. `null` when no
+     * generated metadata was found: redaction is then inert and the user needs to
+     * know that rather than assume protection.
+     */
+    piiTags: {
+        path: string;
+        applied: number;
+    } | null;
     /** Random per-process session token the UI sends via cookie. */
     authToken: string;
     /** Full URL including `?token=...` — safe to print for the user. */
@@ -138,6 +154,32 @@ export interface StudioContext {
 export declare function startStudio(options: StudioOptions): Promise<StudioHandle>;
 export declare function handleRequest(req: IncomingMessage, res: ServerResponse, ctx: StudioContext): Promise<void>;
 export declare function apiDemoMode(req: IncomingMessage, res: ServerResponse, ctx: StudioContext): Promise<void>;
+/** One clickable reference from a column on this table to a row in another. */
+export interface ForeignKeyLink {
+    /** Column on THIS table whose cell becomes the link. */
+    column: string;
+    /** Relation the link was derived from. */
+    relation: string;
+    /** Table the reference points at. */
+    targetTable: string;
+    /** Column on the target table the value is matched against. */
+    targetColumn: string;
+}
+/** One reverse jump: rows in a child table that reference this table. */
+export interface ReferencedByLink {
+    /** Column on THIS table whose value the child column matches (usually the PK). */
+    column: string;
+    /** Relation the link was derived from. */
+    relation: string;
+    /** Child table holding the referencing rows. */
+    targetTable: string;
+    /** Referencing column on the child table. */
+    targetColumn: string;
+}
+export declare function relationLinksForTable(table: TableMetadata, metadata: SchemaMetadata, showPii: boolean): {
+    foreignKeys: ForeignKeyLink[];
+    referencedBy: ReferencedByLink[];
+};
 export declare function apiTableRows(res: ServerResponse, ctx: StudioContext, rawTableName: string, params: URLSearchParams): Promise<void>;
 export declare function resolveColumnName(table: TableMetadata, nameOrField: string): string | null;
 export declare function isTextishType(pgType: string): boolean;

package/dist/cli/studio.js

@@ -43,8 +43,10 @@ import { createServer } from 'node:http';
 import { platform } from 'node:os';
 import { dirname, resolve as pathResolve } from 'node:path';
 import pg from 'pg';
+import { ValidationError } from '../errors.js';
 import { introspect } from '../introspect.js';
 import { QueryInterface, quoteIdent } from '../query/index.js';
+import { applyPiiTags, loadPiiTags } from './pii-tags.js';
 import { createDemoContext } from './studio-demo.js';
 import { STUDIO_HTML } from './studio-ui.generated.js';
 // ---------------------------------------------------------------------------
@@ -65,6 +67,7 @@ export async function startStudio(options) {
     let metadata;
     let dialect;
     let statementTimeout;
+    let piiTags = null;
     if (demo) {
         // Seeded in-memory SQLite store: no DATABASE_URL, no network. Each launch
         // starts pristine and nothing is ever persisted.
@@ -98,6 +101,14 @@ export async function startStudio(options) {
             include: options.include,
             exclude: options.exclude,
         });
+        // PII tags are code-first only, so a live-introspected schema carries none.
+        // Layer them on from the generated metadata when there is one, and record
+        // what happened so the CLI can be explicit about it at startup.
+        if (options.metadataDir) {
+            const source = loadPiiTags(options.metadataDir);
+            if (source)
+                piiTags = { path: source.path, applied: applyPiiTags(metadata, source.tags) };
+        }
         statementTimeout = options.adapter?.statementTimeout?.(30) ?? {
             // Postgres rejects parameters in `SET LOCAL` (`SET LOCAL ... = $1` is a
             // syntax error). `set_config(name, value, is_local=true)` is the
@@ -147,6 +158,7 @@ export async function startStudio(options) {
     return {
         authToken,
         url,
+        piiTags,
         dispose: async () => {
             await new Promise((resolve) => server.close(() => resolve()));
             await pool.end();
@@ -368,6 +380,8 @@ async function apiSchema(res, ctx) {
             foreignKey: rel.foreignKey,
             referenceKey: rel.referenceKey,
         })),
+        // Click-through navigation targets, derived from relation metadata only.
+        ...relationLinksForTable(tbl, ctx.metadata, ctx.showPii === true),
     }));
     // Row counts (cheap enough to fetch inline).
     const counts = new Map();
@@ -404,6 +418,91 @@ async function apiSchema(res, ctx) {
         demo: ctx.demo === true,
     });
 }
+/** Own-property lookup: a key like `constructor` must not resolve off the prototype. */
+function ownLookup(map, key) {
+    return Object.hasOwn(map, key) ? map[key] : undefined;
+}
+/** True when `columnName` on `table` is PII-tagged and currently redacted. */
+function isRedactedColumn(table, columnName, showPii) {
+    if (showPii)
+        return false;
+    const col = table.columns.find((c) => c.name === columnName);
+    return col?.pii === true;
+}
+/**
+ * Resolve a relation key to a single column name on `table`, or `null`. Composite
+ * (array) keys return null: a composite reference has no single cell to click, so
+ * those relations simply produce no link rather than a half-working one.
+ */
+function singleRelationColumn(table, key) {
+    if (typeof key !== 'string')
+        return null;
+    return resolveColumnName(table, key);
+}
+export function relationLinksForTable(table, metadata, showPii) {
+    const foreignKeys = [];
+    const referencedBy = [];
+    const seenFkColumns = new Set();
+    for (const [name, rel] of Object.entries(table.relations)) {
+        const target = metadata.tables[rel.to];
+        if (!target)
+            continue;
+        if (rel.type === 'belongsTo') {
+            // The FK lives on this table; the reference key on the target.
+            const column = singleRelationColumn(table, rel.foreignKey);
+            const targetColumn = singleRelationColumn(target, rel.referenceKey);
+            if (!column || !targetColumn)
+                continue;
+            if (seenFkColumns.has(column))
+                continue;
+            if (isRedactedColumn(table, column, showPii) || isRedactedColumn(target, targetColumn, showPii))
+                continue;
+            seenFkColumns.add(column);
+            foreignKeys.push({ column, relation: name, targetTable: target.name, targetColumn });
+            continue;
+        }
+        if (rel.type === 'hasMany' || rel.type === 'hasOne') {
+            // The FK lives on the child table; the reference key on this one.
+            const column = singleRelationColumn(table, rel.referenceKey);
+            const targetColumn = singleRelationColumn(target, rel.foreignKey);
+            if (!column || !targetColumn)
+                continue;
+            if (isRedactedColumn(table, column, showPii) || isRedactedColumn(target, targetColumn, showPii))
+                continue;
+            referencedBy.push({ column, relation: name, targetTable: target.name, targetColumn });
+        }
+        // manyToMany deliberately produces no link: navigating it means traversing a
+        // junction table, which the single-column filter path cannot express.
+    }
+    // Inbound references declared only on the OTHER side. A `defineSchema` author
+    // routinely writes `comments.user -> users` without also declaring
+    // `users.comments`, and scanning only this table's own hasMany/hasOne made
+    // those children unreachable even though the child grid visibly renders the
+    // FK. Scan every other table's belongsTo relations that point here.
+    const seenInbound = new Set(referencedBy.map((r) => `${r.targetTable}.${r.targetColumn}`));
+    for (const other of Object.values(metadata.tables)) {
+        if (other.name === table.name)
+            continue;
+        for (const [name, rel] of Object.entries(other.relations)) {
+            if (rel.type !== 'belongsTo' || rel.to !== table.name)
+                continue;
+            const column = singleRelationColumn(table, rel.referenceKey);
+            const targetColumn = singleRelationColumn(other, rel.foreignKey);
+            if (!column || !targetColumn)
+                continue;
+            if (seenInbound.has(`${other.name}.${targetColumn}`))
+                continue;
+            if (isRedactedColumn(table, column, showPii) || isRedactedColumn(other, targetColumn, showPii))
+                continue;
+            seenInbound.add(`${other.name}.${targetColumn}`);
+            // Named for the direction the user travels: from this row, to the rows of
+            // `other` that reference it. `relation` is the child's own relation name,
+            // which is what the child table calls this link.
+            referencedBy.push({ column, relation: name, targetTable: other.name, targetColumn });
+        }
+    }
+    return { foreignKeys, referencedBy };
+}
 // ---------------------------------------------------------------------------
 // API: /api/tables/:name?limit=&offset=&orderBy=&dir=
 // ---------------------------------------------------------------------------
@@ -645,6 +744,63 @@ function parseTableFilters(raw, table, redactedPii) {
 // ---------------------------------------------------------------------------
 // API: /api/builder — Turbine ORM findMany spec runner
 // ---------------------------------------------------------------------------
+/**
+ * Refuse a builder query that FILTERS or SORTS on a redacted PII column.
+ *
+ * Redacting the cells is not enough on its own: `where: { email: { startsWith:
+ * 'a' } }` answers a question about the hidden value, and so does an `isNull`,
+ * and so does an `orderBy`. The Data tab already refuses all three
+ * (`parseTableFilters`); the builder route accepted them, which mattered the
+ * moment PII tags actually started reaching Studio's metadata.
+ *
+ * Walks the whole args tree: top-level `where` / `orderBy`, boolean
+ * combinators, and each `with` level against that relation's target table.
+ * `select` is NOT refused: it returns values, and those values are redacted on
+ * the way out.
+ */
+function assertNoPiiPredicates(args, tableName, metadata, showPii) {
+    if (showPii)
+        return;
+    const visitClause = (node, table, depth) => {
+        if (!table || depth > 10 || node === null || typeof node !== 'object')
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            if (key === 'AND' || key === 'OR' || key === 'NOT') {
+                for (const item of Array.isArray(value) ? value : [value])
+                    visitClause(item, table, depth + 1);
+                continue;
+            }
+            const relation = Object.hasOwn(table.relations, key) ? table.relations[key] : undefined;
+            if (relation) {
+                // some / none / every / is / isNot wrappers all resolve against the target.
+                visitClause(value, metadata.tables[relation.to], depth + 1);
+                continue;
+            }
+            const column = ownLookup(table.columnMap, key) ?? key;
+            if (isRedactedColumn(table, column, showPii)) {
+                throw new ValidationError(`[turbine] Column "${column}" on "${table.name}" is PII-tagged and redacted, so it cannot be used ` +
+                    `in a where or orderBy: filtering or sorting on a hidden value reveals it. ` +
+                    `Restart Studio with --show-pii to query it.`);
+            }
+        }
+    };
+    const visitLevel = (level, table, depth) => {
+        if (!table || depth > 10)
+            return;
+        visitClause(level.where, table, depth);
+        visitClause(level.orderBy, table, depth);
+        const withClause = level.with;
+        if (!withClause || typeof withClause !== 'object')
+            return;
+        for (const [relName, spec] of Object.entries(withClause)) {
+            const relation = Object.hasOwn(table.relations, relName) ? table.relations[relName] : undefined;
+            if (!relation || spec === true || spec === null || typeof spec !== 'object')
+                continue;
+            visitLevel(spec, metadata.tables[relation.to], depth + 1);
+        }
+    };
+    visitLevel(args, metadata.tables[tableName], 0);
+}
 export async function apiBuilder(req, res, ctx) {
     const body = await readJsonBody(req);
     const tableName = typeof body?.table === 'string' ? body.table : '';
@@ -663,6 +819,7 @@ export async function apiBuilder(req, res, ctx) {
             // when unset.
             dialect: ctx.dialect,
         });
+        assertNoPiiPredicates(args, tableName, ctx.metadata, ctx.showPii === true);
         deferred = qi.buildFindMany(args);
     }
     catch (err) {

package/dist/cli/ui.js

@@ -212,9 +212,14 @@ export function stripAnsi(s) {
 // ---------------------------------------------------------------------------
 export function redactUrl(url) {
     return (url
-        // Userinfo credentials: `:secret@` in any authority (global: a string may
-        // carry more than one URL, e.g. a primary + replica connection pair).
-        .replace(/:([^@/:]+)@/g, ':***@')
+        // Userinfo credentials. Anchored on `<scheme>://<user>:` and consuming up
+        // to the LAST `@` before the next `/` (or end of authority), because a
+        // password may legally contain `:`, `/`, and even `@` in percent-decoded
+        // form. The previous `:([^@/:]+)@` could not span any of those, so
+        // `postgres://u:pa/ss@host/db` came through completely unredacted and
+        // `postgres://u:a@b@host/db` leaked the tail. Global: one string may
+        // carry several URLs (a primary + replica pair).
+        .replace(/(\w+:\/\/[^/@\s]*?:)[^\s]*?@(?=[^@\s]*(?:[/?#]|$))/g, '$1***@')
         // Query-string password params: `password=`, `sslpassword=`, and similar,
         // case-insensitive. Value runs up to the next `&`, `#`, or end of string.
         .replace(/([?&][^=&#]*password)=([^&#]*)/gi, '$1=***'));

package/dist/client.js

@@ -306,9 +306,29 @@ export class TurbineClient {
         // constructor with an opaque "Cannot read properties of undefined
         // (reading 'tables')". Fail fast with an actionable message instead.
         if (!schema || typeof schema !== 'object' || !schema.tables) {
+            // A `defineSchema()` result is the most common wrong shape here: it is a
+            // SchemaDef (`{ tables: { users: { columns: { id: ... } } } }`-ish builder
+            // output), not runtime SchemaMetadata, so name the conversion rather than
+            // just the requirement.
+            const looksLikeSchemaDef = schema !== null && typeof schema === 'object' && Object.hasOwn(schema, 'name') === false;
             throw new ValidationError('[turbine] TurbineClient requires schema metadata as its second argument. ' +
                 'Run `npx turbine generate` and use the generated client (`turbine()` from your output dir), ' +
-                'or pass the generated `schemaMetadata` object: new TurbineClient(config, schemaMetadata).');
+                'or pass the generated `schemaMetadata` object: new TurbineClient(config, schemaMetadata).' +
+                (looksLikeSchemaDef
+                    ? ' If you have a `defineSchema()` result, convert it first with `schemaDefToMetadata(def)`.'
+                    : ''));
+        }
+        // A wrong-SHAPED schema (a `defineSchema()` result, whose tables carry no
+        // `columns` array) used to survive this check and die later as
+        // `TypeError: this.tableMeta.columns is not iterable`, several frames from
+        // the cause. Validate one table's shape here, where the fix is obvious.
+        for (const [name, meta] of Object.entries(schema.tables)) {
+            if (!meta || typeof meta !== 'object' || !Array.isArray(meta.columns)) {
+                throw new ValidationError(`[turbine] Table "${name}" in the schema passed to TurbineClient has no \`columns\` array, so this is ` +
+                    'not runtime SchemaMetadata. A `defineSchema()` result is a SchemaDef: convert it with ' +
+                    '`schemaDefToMetadata(def)`, or use the metadata emitted by `npx turbine generate`.');
+            }
+            break;
         }
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.

package/dist/dialect.d.ts

@@ -298,6 +298,25 @@ export interface Dialect {
     readonly supportsUpsertUpdateWhere?: boolean;
     /** Whether this dialect/engine supports pgvector distance ops (KNN / distance WHERE). */
     readonly supportsVector: boolean;
+    /**
+     * Whether this dialect/engine supports the PostgreSQL full-text `search`
+     * filter (`to_tsvector(...) @@ to_tsquery(...)`). Optional: absent is treated
+     * as `false`, so only dialects that set it true admit a `search` filter and
+     * every other engine throws {@link UnsupportedFeatureError} (E017) instead of
+     * emitting SQL its parser cannot read. MySQL `MATCH … AGAINST` and SQL Server
+     * `CONTAINS` are different surfaces with different index requirements, so they
+     * deliberately stay `false` rather than silently changing the semantics.
+     */
+    readonly supportsFullTextSearch?: boolean;
+    /**
+     * Whether this dialect/engine supports native array columns and the array
+     * filter operators built on them (`has` → `= ANY(col)`, `hasEvery` → `@>`,
+     * `hasSome` → `&&`, `isEmpty` → `cardinality(col)`). Optional: absent is
+     * treated as `false`, so SQLite / MySQL / SQL Server (which have no array
+     * column type; a JSON column is not the same thing) throw
+     * {@link UnsupportedFeatureError} (E017) instead of emitting `ANY(...)`.
+     */
+    readonly supportsArrayColumns?: boolean;
     /** Whether this dialect/engine supports LISTEN/NOTIFY realtime pub/sub. */
     readonly supportsListenNotify: boolean;
     /** Whether this dialect/engine supports row-level-security session GUCs (set_config). */

package/dist/dialect.js

@@ -19,6 +19,8 @@ export const postgresDialect = {
     nullJsonLiteral: 'NULL',
     aggSupportsInlineOrderBy: true,
     supportsVector: true,
+    supportsFullTextSearch: true,
+    supportsArrayColumns: true,
     supportsListenNotify: true,
     supportsRLS: true,
     supportsAdvisoryLock: true,

package/dist/index-advisor.d.ts

@@ -98,6 +98,13 @@ export interface DoctorProbeColumns {
  * 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.

package/dist/index-stats.d.ts

@@ -101,11 +101,28 @@ export interface TableStats {
     /** 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;
@@ -215,6 +232,21 @@ export interface UnusedIndex {
     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:
@@ -225,6 +257,10 @@ export interface UnusedIndex {
  */
 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 {
@@ -245,6 +281,9 @@ export interface RedundantIndex {
  * 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[];
 /**
@@ -257,13 +296,21 @@ export interface DoctorIndexAudit {
     columns: string[];
     idxScan: number;
     sizeBytes: number | null;
-    dropSql: string;
+    /** `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:
@@ -278,6 +325,10 @@ export declare function auditDoctorIndexes(snapshot: StatsSnapshot, doctorNames:
     columns: string[];
 }>>, options?: {
     minScans?: number;
+    relationProbes?: Array<{
+        table: string;
+        columns: string[];
+    }>;
 }): DoctorIndexAudit[];
 /**
  * Whether the snapshot is trustworthy enough to render tier verdicts. Empty,