turbine-orm 0.65.0 → 0.66.0

package/dist/query/writes.d.ts

@@ -188,7 +188,7 @@ export declare function assertBindableSetValue(qi: BuilderCtx, key: string, valu
  * Fingerprint SET clauses for update/updateMany.
  * Captures key names + operator types (set/increment/etc) but not values.
  */
-export declare function fingerprintSet(_qi: BuilderCtx, data: Record<string, unknown>): string;
+export declare function fingerprintSet(qi: BuilderCtx, data: Record<string, unknown>): string;
 /**
  * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
  */

package/dist/query/writes.js

@@ -15,7 +15,7 @@ import { camelToSnake, snakeToCamel } from '../schema.js';
 import { expandCompoundUniqueWhere } from './compound-unique.js';
 import { isUnmatchedPlainObject, UPDATE_OPERATOR_KEYS } from './filters.js';
 import { resolveSkipGlobalFilters, resolveUnsafeFlag } from './types.js';
-import { coerceTemporalValue, resolveColumnName } from './utils.js';
+import { canonicalWriteEntries, coerceTemporalValue, resolveColumnName } from './utils.js';
 import * as whereMod from './where.js';
 /**
  * Normalize one `data` value before it is bound as a write param.
@@ -115,7 +115,7 @@ function buildDefaultValuesInsert(qi, rowCount, skipDuplicates) {
 export function buildCreate(qi, args) {
     assertWritable(qi, 'create');
     assertNoGeneratedColumns(qi, args.data, 'create');
-    const entries = Object.entries(args.data).filter(([, v]) => v !== undefined);
+    const entries = writeEntries(qi, args.data);
     const columns = entries.map(([k]) => qi.toSqlColumn(k));
     const params = entries.map(([k, v]) => coerceWriteValue(qi, k, v));
     // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
@@ -176,15 +176,39 @@ export function makeCreateReselect(qi, insertSql, insertParams, data) {
     };
 }
 /**
- * The fields a write's `data` object actually names.
+ * The `[key, value]` pairs a write's `data` object actually names, in the
+ * table's own column order.
  *
  * A key whose value is `undefined` is NOT named: single-row {@link buildCreate}
  * filters those out of its column list, so the column takes its declared
- * default. `createMany` reads its rows through this same helper, so
- * `{ n: undefined }` and `{}` mean the identical thing on both paths.
+ * default. `createMany` reads its rows through {@link definedKeys}, which is
+ * this function's key half, so `{ n: undefined }` and `{}` mean the identical
+ * thing on both paths.
+ *
+ * THE ORDERING IS A SECURITY BOUND, not tidiness, and it is the whole reason
+ * this is one function rather than an `Object.entries` at each site. A write's
+ * column list is SQL TEXT: `SET "a" = $1, "b" = $2` and `SET "b" = $1, "a" = $2`
+ * are the same write and two different permanently-cached server-side prepared
+ * statements. `JSON.parse` preserves insertion order, so
+ * `update({ where, data: JSON.parse(reqBody) })` (an ordinary REST handler)
+ * lets the request body pick that order, with no array, no arity, and nothing
+ * the caller needs to know. Measured on PostgreSQL 16: 720 PATCH bodies
+ * carrying the SAME six keys in different orders left 720 prepared statements
+ * and 2.8 MB of CachedPlanSource on one connection. See
+ * {@link canonicalWriteEntries} for the ordering rule and why duplicates are
+ * deliberately preserved.
+ *
+ * Every consumer of this list must use THIS function: the SET-clause build, the
+ * cache fingerprint ({@link fingerprintSet}) and the param collector
+ * ({@link collectSetParams}) must enumerate one identical order or the cached
+ * statement and its params describe different writes.
  */
-function definedKeys(row) {
-    return Object.keys(row).filter((k) => row[k] !== undefined);
+function writeEntries(qi, data) {
+    return canonicalWriteEntries(qi.tableMeta, Object.entries(data).filter(([, v]) => v !== undefined));
+}
+/** The key half of {@link writeEntries}, for the paths that need names only. */
+function definedKeys(qi, row) {
+    return writeEntries(qi, row).map(([k]) => k);
 }
 /**
  * Refuse a `createMany` whose rows do not all name the SAME fields.
@@ -214,7 +238,7 @@ function definedKeys(row) {
 function assertUniformCreateManyRows(qi, rows, firstKeys) {
     const expected = new Set(firstKeys);
     for (let i = 1; i < rows.length; i++) {
-        const rowKeys = definedKeys(rows[i]);
+        const rowKeys = definedKeys(qi, rows[i]);
         const unexpected = rowKeys.filter((k) => !expected.has(k));
         // No stranger and the same count means the same set (object keys are unique).
         if (unexpected.length === 0 && rowKeys.length === expected.size)
@@ -252,7 +276,7 @@ export function buildCreateMany(qi, args) {
     for (const row of args.data) {
         assertNoGeneratedColumns(qi, row, 'createMany');
     }
-    const keys = definedKeys(args.data[0]);
+    const keys = definedKeys(qi, args.data[0]);
     assertUniformCreateManyRows(qi, args.data, keys);
     // No column named by the first row: every row is pure defaults (the bulk
     // counterpart of `create({ data: {} })`, see buildDefaultValuesInsert). The
@@ -360,7 +384,7 @@ export function buildUpdate(qi, args) {
     const ck = lock ? null : `u:${setFp}|${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;
     const params = [];
     const buildSql = (freshParams) => {
-        const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
+        const setEntries = writeEntries(qi, dataObj);
         const setClauses = setEntries.map(([k, v]) => buildSetClause(qi, k, v, freshParams));
         if (lock) {
             const versionCol = qi.toSqlColumn(lock.field);
@@ -510,7 +534,7 @@ export function buildUpsert(qi, args) {
     // Prisma compound-unique selector on the conflict target → its member columns.
     const upsertWhere = expandCompoundUniqueWhere(qi.tableMeta, args.where);
     // Build the INSERT part from create data
-    const createEntries = Object.entries(args.create).filter(([, v]) => v !== undefined);
+    const createEntries = writeEntries(qi, args.create);
     const columns = createEntries.map(([k]) => qi.toSqlColumn(k));
     const createParams = createEntries.map(([k, v]) => coerceWriteValue(qi, k, v));
     // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
@@ -519,7 +543,7 @@ export function buildUpsert(qi, args) {
     const conflictKeys = Object.keys(upsertWhere).filter((k) => upsertWhere[k] !== undefined);
     const conflictColumns = conflictKeys.map((k) => qi.toSqlColumn(k));
     // Build the UPDATE SET part
-    const updateEntries = Object.entries(args.update).filter(([, v]) => v !== undefined);
+    const updateEntries = writeEntries(qi, args.update);
     let paramIdx = createParams.length + 1;
     const setClauses = updateEntries.map(([k]) => {
         const clause = `${qi.toSqlColumn(k)} = ${qi.p(paramIdx)}${whereMod.enumCastSuffix(qi, qi.toColumn(k))}`;
@@ -597,7 +621,7 @@ export function buildUpdateMany(qi, args) {
     const ck = `um:${setFp}|${whereFp}${whereMod.globalFilterCacheSegment(qi)}`;
     const params = [];
     const buildSql = (freshParams) => {
-        const setEntries = Object.entries(dataObj).filter(([, v]) => v !== undefined);
+        const setEntries = writeEntries(qi, dataObj);
         const setClauses = setEntries.map(([k, v]) => buildSetClause(qi, k, v, freshParams));
         const whereClause = whereMod.buildWhereClause(qi, whereObj, freshParams);
         const whereSql = whereClause ? ` WHERE ${whereClause}` : '';
@@ -922,8 +946,8 @@ export function assertBindableSetValue(qi, key, value) {
  * Fingerprint SET clauses for update/updateMany.
  * Captures key names + operator types (set/increment/etc) but not values.
  */
-export function fingerprintSet(_qi, data) {
-    const entries = Object.entries(data).filter(([, v]) => v !== undefined);
+export function fingerprintSet(qi, data) {
+    const entries = writeEntries(qi, data);
     const parts = [];
     for (const [k, v] of entries) {
         if (v !== null &&
@@ -945,7 +969,7 @@ export function fingerprintSet(_qi, data) {
  * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
  */
 export function collectSetParams(qi, data, params) {
-    const entries = Object.entries(data).filter(([, v]) => v !== undefined);
+    const entries = writeEntries(qi, data);
     for (const [k, v] of entries) {
         if (v !== null &&
             typeof v === 'object' &&

package/dist/schema-builder.d.ts

@@ -70,7 +70,8 @@ export interface ColumnDef {
      * `schemaDefToMetadata` / codegen, onto
      * {@link import('./schema.js').ColumnMetadata.pii}. A PII column is excluded
      * from default projections (read back only via an explicit `select` or
-     * `includePii: true`) and redacted by Studio. Introspection never auto-tags PII.
+     * `includePii: UNSAFE`, the imported sentinel symbol) and redacted by Studio.
+     * Introspection never auto-tags PII.
      */
     pii?: boolean;
     /**

package/dist/schema-sql.d.ts

@@ -8,7 +8,7 @@ import { type DestructiveStatement } from './cli/destructive.js';
 import { type Dialect } from './dialect.js';
 import { ValidationError } from './errors.js';
 import { type ReferentialAction } from './schema.js';
-import { type ColumnIndexDef, type SchemaDef, type TableDef } from './schema-builder.js';
+import { type ColumnConfig, type ColumnIndexDef, type SchemaDef, type TableDef } from './schema-builder.js';
 export interface SchemaSqlOptions {
     /** SQL dialect used for DDL generation. Defaults to PostgreSQL. */
     dialect?: Dialect;
@@ -154,13 +154,92 @@ export declare function diffCheckConstraints(table: string, schemaChecks: readon
     statements: string[];
     reverseStatements: string[];
 };
+/** Options for {@link schemaDiff} and {@link schemaPush}. */
+export interface SchemaDiffOptions {
+    /**
+     * Postgres NAMESPACE the diff reads (default `public`).
+     *
+     * Every catalog read here used to hardcode `'public'` while `generate`,
+     * `pull`, `doctor`, and `studio` all honored the configured schema. Against a
+     * table in a non-public schema the diff therefore saw nothing and emitted
+     * `CREATE TABLE "users"` (a duplicate in public); worse, when a legacy copy of
+     * the table still sat in `public` (the usual state after moving to a dedicated
+     * schema) it read THAT one and emitted ALTER / DROP COLUMN against the wrong
+     * table. Defaults to `public`, so a project with no schema configured emits
+     * byte-identical SQL.
+     */
+    schema?: string;
+}
 /**
  * Compare a SchemaDef against a live Postgres database and return the diff.
  *
- * Connects to the database, inspects the public schema, and computes what
- * DDL is needed to make the database match the schema definition.
+ * Connects to the database, inspects `options.schema` (default `public`), and
+ * computes what DDL is needed to make the database match the schema definition.
  */
-export declare function schemaDiff(schema: SchemaDef, connectionString: string): Promise<DiffResult>;
+export declare function schemaDiff(schema: SchemaDef, connectionString: string, options?: SchemaDiffOptions): Promise<DiffResult>;
+/** The type-relevant subset of {@link DbColumn}, so {@link planTypeChange} stays testable. */
+export interface DbColumnType {
+    udtName: string;
+    maxLength: number | null;
+    numericPrecision: number | null;
+    numericScale: number | null;
+    /**
+     * `format_type(atttypid, atttypmod)` from pg_catalog: the type exactly as
+     * Postgres would write it, e.g. `character varying(255)[]`, `vector(3)`,
+     * `numeric(10,2)`, `app."Probe"`. Read alongside information_schema because
+     * information_schema cannot express an array element's length modifier or a
+     * pgvector dimension count, and because it is the only spelling of an
+     * unmapped type that is guaranteed to be valid, correctly quoted and
+     * correctly schema-qualified DDL. Null only when a caller builds the value by
+     * hand (the live diff always populates it).
+     */
+    formattedType: string | null;
+}
+/**
+ * What the diff should do about one column's type.
+ *
+ * `alter` carries `needsUsing` (see {@link planTypeChange}) and, when the
+ * conversion can lose or reject data, a `loss` sentence naming the SPECIFIC
+ * loss. `warn` is for a difference the code-first schema cannot express, where
+ * emitting DDL would destroy an intentional database-side constraint.
+ */
+export type TypeChangePlan = {
+    kind: 'none';
+} | {
+    kind: 'alter';
+    needsUsing: boolean;
+    loss?: string;
+} | {
+    kind: 'warn';
+    reason: string;
+};
+/**
+ * Decide what the diff should emit for one column's type.
+ *
+ * Two things this deliberately does that the previous `udtName !== expectedUdt`
+ * check did not:
+ *
+ *   1. It compares LENGTH and NUMERIC PRECISION, not just the UDT name. A
+ *      declared `varchar(10)` against a database `VARCHAR(255)` produced no
+ *      statement and no warning, so `push` printed "Database is already in
+ *      sync" for a schema that genuinely differed. The widening direction is
+ *      the operationally painful one: the schema says 255, the column is 10,
+ *      push says in sync, and writes fail at runtime with "value too long".
+ *   2. It reports `needsUsing` FALSE for a same-family conversion. The old
+ *      statement always appended `USING col::type`, and an EXPLICIT cast to
+ *      `varchar(n)` TRUNCATES where the plain assignment cast raises "value too
+ *      long". Postgres refuses that migration on its own; the generated `USING`
+ *      converted the refusal into silent data amputation. Same shape for
+ *      `numeric -> integer` and `timestamptz -> date`. `USING` is emitted only
+ *      where the conversion genuinely needs it (text to uuid, text to an enum,
+ *      anything crossing a type family), where no assignment cast exists.
+ *
+ * Numeric PRECISION drift gets a warning rather than a statement: `defineSchema`
+ * has no way to declare `numeric(10, 2)`, so every such column would otherwise
+ * get a table-rewriting `ALTER ... TYPE NUMERIC` on every push, discarding a
+ * constraint the schema never had the vocabulary to ask for.
+ */
+export declare function planTypeChange(config: ColumnConfig, dbCol: DbColumnType, column: string): TypeChangePlan;
 /**
  * Scan a set of diff statements for data-destroying operations, using the same
  * conservative scanner (`scanDestructiveSql`) that gates `migrate up`/`down`.
@@ -204,11 +283,22 @@ export declare class DestructivePushRefusal extends ValidationError {
  * `allowDestructive: true` is passed. The CLI (`turbine push`) catches this and
  * prompts for the same typed confirmation as `migrate up`; programmatic callers
  * must opt in explicitly.
+ *
+ * `options.schema` (default `public`) scopes BOTH halves: the diff reads that
+ * namespace, and the generated DDL (which names tables unqualified) is executed
+ * with a transaction-local `search_path` pinned so the target schema resolves
+ * FIRST. Without the second half a diff that correctly found nothing in `app`
+ * would still emit `CREATE TABLE "users"` into whatever the connection's
+ * search_path happens to resolve to. The pin is unconditional (`public` is a
+ * target like any other, since a role's own search_path may not lead there),
+ * refuses a schema that does not exist, and APPENDS the connection's existing
+ * path so types living elsewhere still resolve. See {@link pinSearchPath}.
  */
 export declare function schemaPush(schema: SchemaDef, connectionString: string, options?: {
     dryRun?: boolean;
     allowDestructive?: boolean;
     precomputedDiff?: DiffResult;
+    schema?: string;
 }): Promise<PushResult>;
 /**
  * Generate the full DDL as a single formatted string.