turbine-orm 0.72.0 → 0.73.0

package/dist/query/option-surface.js

@@ -51,6 +51,12 @@
  *
  * @module
  */
+// Runtime imports, and the only ones in this file: the unknown-key warning at
+// the bottom needs the once-per-process registry and the name suggester. Both
+// are leaves that do not import this module, so the type-only shape of
+// everything above is unaffected.
+import { suggestKey } from './utils.js';
+import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 export const FIND_UNIQUE_OPTIONS = {
     where: 'prisma',
     select: 'prisma',
@@ -79,7 +85,13 @@ export const FIND_MANY_OPTIONS = {
     omit: 'prisma',
     orderBy: 'prisma',
     cursor: 'prisma',
+    // `take` and `skip` are Prisma's own spellings and core accepts them as
+    // aliases, but they stay hand-translated because Prisma gives them meanings
+    // core does not have: a NEGATIVE `take` pages from the end, and `skip: 1`
+    // beside a `cursor` is the exclusive-pagination idiom. Forwarding either
+    // verbatim would hand core a number that means something else.
     take: 'prisma',
+    skip: 'prisma',
     distinct: 'prisma',
     relationLoadStrategy: 'prisma',
     with: 'nativeAlias',
@@ -226,3 +238,81 @@ export function applyNativeOptions(table, src, dst) {
 export function optionKeysOfKind(table, ...kinds) {
     return Object.keys(table).filter((k) => kinds.includes(table[k]));
 }
+// ---------------------------------------------------------------------------
+// Unknown-key diagnostic
+// ---------------------------------------------------------------------------
+/**
+ * The operations a caller can invoke, mapped to the table that describes their
+ * legal keys. The `*OrThrow` and `findFirst` variants take the same args as the
+ * method they are built on, so they share its table rather than getting a copy
+ * that could drift from it.
+ */
+const OPERATION_TABLE = {
+    ...ALL_OPTION_TABLES,
+    findFirst: FIND_MANY_OPTIONS,
+    findFirstOrThrow: FIND_MANY_OPTIONS,
+    findUniqueOrThrow: FIND_UNIQUE_OPTIONS,
+    findManyStreamBatches: FIND_MANY_STREAM_OPTIONS,
+};
+/**
+ * Prisma spellings that name a real Turbine option under a different word.
+ *
+ * Only spellings whose Turbine equivalent EXISTS belong here: the message tells
+ * the caller what to write instead, so a key with no equivalent would produce
+ * advice that does not work. `take` / `skip` were once on this list and are now
+ * accepted outright.
+ */
+const PRISMA_SPELLING = {
+    include: 'with',
+};
+/**
+ * Dev-mode warning for a key that is not part of the operation's option
+ * surface, and is therefore doing nothing.
+ *
+ * The motivating case is `include`. It is Prisma's word for `with`, it is what
+ * a model or a developer coming from Prisma reaches for first, and an
+ * unrecognized key is simply ignored: the query runs, returns rows, and the
+ * relation the caller asked for is absent. No error, no empty array, just a
+ * missing key on every row. A cross-model eval measured this as the single
+ * largest source of confidently-wrong queries against Turbine, and every one of
+ * them looked like a success from inside the process.
+ *
+ * A WARNING and never an error, deliberately. Refusing an unknown key would
+ * break `findMany({ ...someOptionsBag })`, which is ordinary code, and the
+ * option surface grows: a caller pinned to an older minor would have their
+ * working query start throwing. A warning costs a correct program nothing and
+ * tells an incorrect one exactly what happened.
+ *
+ * Dev-only, once per `table.operation.key` per process, and total: the whole
+ * body is wrapped, because a diagnostic must never be the reason a query fails.
+ */
+export function warnUnknownQueryOptions(table, operation, args) {
+    if (process.env.NODE_ENV === 'production')
+        return;
+    if (args === null || typeof args !== 'object' || Array.isArray(args))
+        return;
+    const known = OPERATION_TABLE[operation];
+    if (!known)
+        return;
+    try {
+        for (const key of Object.keys(args)) {
+            // `{ ...maybeOptions }` routinely materializes keys with no value.
+            // Nothing is being ignored when the value is undefined.
+            if (args[key] === undefined)
+                continue;
+            if (Object.hasOwn(known, key))
+                continue;
+            if (!shouldWarnOnce(WARN_NS.unknownQueryOption, `${table}.${operation}.${key}`))
+                continue;
+            const prismaSpelling = PRISMA_SPELLING[key];
+            const suggestion = prismaSpelling ?? suggestKey(key, Object.keys(known));
+            const because = prismaSpelling ? ` Turbine spells this "${prismaSpelling}".` : '';
+            console.warn(`[turbine] unknown option "${key}" in ${table}.${operation}(), it is ignored.${because}` +
+                (!prismaSpelling && suggestion ? ` Did you mean "${suggestion}"?` : ''));
+        }
+    }
+    catch {
+        // Key enumeration is the only thing that can fail here (a Proxy whose
+        // ownKeys throws), and it must not take the query with it.
+    }
+}

package/dist/query/types.d.ts

@@ -629,8 +629,22 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
     with?: W;
     /** Cursor-based pagination: start after this row */
     cursor?: Partial<T>;
-    /** Number of records to take (used with cursor) */
+    /**
+     * Prisma's spelling of {@link FindManyArgs.limit}. Folded into `limit` before
+     * anything reads it; passing both with different values is a
+     * `ValidationError`.
+     */
     take?: number;
+    /**
+     * Prisma's spelling of {@link FindManyArgs.offset}. Folded into `offset`
+     * before anything reads it; passing both with different values is a
+     * `ValidationError`.
+     *
+     * Accepted since 0.73.0. Before that `take` was recognized and `skip` was
+     * not, so the Prisma pair `{ take, skip }` silently returned the first page
+     * however far the caller thought they had paged.
+     */
+    skip?: number;
     /** De-duplicate results by specified fields */
     distinct?: (keyof T & string)[];
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */

package/dist/query/utils.d.ts

@@ -728,3 +728,26 @@ export declare function warnRedundantSortTerm(table: string, clause: string, dro
  */
 export declare function selectNamesNothingMessage(table: string): string;
 export declare function selectOmitExclusiveMessage(table: string): string;
+/**
+ * The Prisma pagination aliases, folded into Turbine's own spelling ONCE,
+ * before anything reads them.
+ *
+ * Turbine's names are `limit` / `offset`; Prisma's are `take` / `skip`. `take`
+ * was accepted and `skip` was not, which is the worst of the three possible
+ * states: `{ take: 20, skip: 40 }` is what a Prisma habit writes, it looks
+ * accepted because half of it is, and the query silently returns page one
+ * forever. An unknown key is at least inert on its own; a HALF-recognized pair
+ * changes the answer.
+ *
+ * Folded here rather than read at each site deliberately. `take` used to be
+ * handled by six separate `args?.take ?? args?.limit` reads, one of which is
+ * the SQL-cache FINGERPRINT, so adding `skip` the same way would have meant
+ * teaching six places about it and a miss in the fingerprint is not a missing
+ * feature, it is two different pages sharing one cached statement. Normalizing
+ * up front leaves `limit` / `offset` as the single authority and the aliases
+ * cease to exist below this line.
+ *
+ * Returns the SAME object when neither alias is present, so the common path
+ * allocates nothing.
+ */
+export declare function normalizePagination<A extends object | undefined>(args: A): A;

package/dist/query/utils.js

@@ -4,6 +4,7 @@
  * Standalone utility functions and classes used by the query builder.
  */
 import pg from 'pg';
+import { ValidationError } from '../errors.js';
 import { camelToSnake, localDateTimeKind, snakeToCamel, timeOfDayKind } from '../schema.js';
 import { shouldWarnOnce, WARN_NS } from './warn-registry.js';
 // ---------------------------------------------------------------------------
@@ -1492,3 +1493,58 @@ export function selectOmitExclusiveMessage(table) {
     return (`[turbine] "select" and "omit" are mutually exclusive (on table "${table}"). ` +
         `A select already lists exactly the fields you want.`);
 }
+/**
+ * The Prisma pagination aliases, folded into Turbine's own spelling ONCE,
+ * before anything reads them.
+ *
+ * Turbine's names are `limit` / `offset`; Prisma's are `take` / `skip`. `take`
+ * was accepted and `skip` was not, which is the worst of the three possible
+ * states: `{ take: 20, skip: 40 }` is what a Prisma habit writes, it looks
+ * accepted because half of it is, and the query silently returns page one
+ * forever. An unknown key is at least inert on its own; a HALF-recognized pair
+ * changes the answer.
+ *
+ * Folded here rather than read at each site deliberately. `take` used to be
+ * handled by six separate `args?.take ?? args?.limit` reads, one of which is
+ * the SQL-cache FINGERPRINT, so adding `skip` the same way would have meant
+ * teaching six places about it and a miss in the fingerprint is not a missing
+ * feature, it is two different pages sharing one cached statement. Normalizing
+ * up front leaves `limit` / `offset` as the single authority and the aliases
+ * cease to exist below this line.
+ *
+ * Returns the SAME object when neither alias is present, so the common path
+ * allocates nothing.
+ */
+export function normalizePagination(args) {
+    if (!args)
+        return args;
+    const a = args;
+    if (a.take === undefined && a.skip === undefined)
+        return args;
+    const out = { ...args };
+    if (a.take !== undefined) {
+        assertAliasAgrees('take', a.take, 'limit', a.limit);
+        out.limit = a.take;
+        delete out.take;
+    }
+    if (a.skip !== undefined) {
+        assertAliasAgrees('skip', a.skip, 'offset', a.offset);
+        out.offset = a.skip;
+        delete out.skip;
+    }
+    return out;
+}
+/**
+ * Both spellings of one bound, disagreeing. Refused rather than resolved: the
+ * old `take ?? limit` silently preferred one of the two numbers the caller
+ * wrote, and there is no reading of `{ limit: 10, take: 5 }` that makes one of
+ * them the intended answer. Equal values are accepted, since there is nothing
+ * to choose between.
+ */
+function assertAliasAgrees(alias, aliasValue, native, nativeValue) {
+    if (nativeValue === undefined || nativeValue === aliasValue)
+        return;
+    throw new ValidationError(`[turbine] "${alias}" and "${native}" are the same option and were given different values ` +
+        `(${alias}: ${String(aliasValue)}, ${native}: ${String(nativeValue)}). ` +
+        `"${alias}" is Prisma's spelling of "${native}"; pass one of them.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "description": "Postgres-native TypeScript ORM, runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "//exports": "Each subpath declares its types PER CONDITION. A single shared top-level \"types\" resolves to the ESM declarations for `require` too, which is TS1479 (\"is an ES module ... cannot be require()d\") for any CJS consumer on moduleResolution node16/nodenext. The require condition points at dist/cjs, which ships its own {\"type\":\"commonjs\"} package.json, so those declarations are CJS declarations. Gated in CI by publint + @arethetypeswrong/cli + a real .cts consumer typecheck (see the package-types job in ci.yml).",
@@ -107,6 +107,7 @@
     "!dist/**/*.js.map",
     "!dist/**/examples.*",
     "!dist/**/*.d.ts.map",
+    "skills",
     "LICENSE",
     "README.md"
   ],

package/skills/turbine-orm/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: turbine-orm
+description: Use when writing or debugging Turbine ORM queries in TypeScript - covers the with clause, WHERE operators, relation filters, aggregates, groupBy having, pagination, JSON paths, and the errors each one throws
+---
+
+# Writing Turbine queries
+
+Turbine is a Postgres-first TypeScript ORM with a Prisma-shaped API. If you know
+Prisma, four differences account for most first-try failures, and they are the
+first four sections here.
+
+Every construct below is executed against a live database by
+`evals/src/verify-skill.ts` in the turbine-orm repository, on every release. A
+claim in this file that stops being true fails that check by name.
+
+## 1. Relations are `with`, never `include`
+
+```ts
+const orders = await db.orders.findMany({
+  select: { id: true, total: true },
+  with: { customer: { select: { email: true } } },
+});
+```
+
+`include` is Prisma's word. Turbine ignores an unrecognized option, so an
+`include` runs, returns rows, and the relation is simply absent from every one
+of them. Since 0.73.0 it also prints a dev-mode warning naming `with`; in
+production it is silent.
+
+## 2. Relation names are derived, and not from the column
+
+A relation name is not the foreign-key column, and not always the table name:
+
+- **belongsTo** (the side holding the FK) is the target table, singularised and
+  camelCased. `guild_id` on `cheese_wheels` gives the relation `guild`.
+- **hasMany** (the side pointed at) is the child table, camelCased and left
+  plural: `cheese_wheels` gives `cheeseWheels`.
+- **manyToMany** across a junction is named for the FAR table, not the junction.
+  With `wheel_cultures` joining `cheese_wheels` and `cultures`, the relation on
+  `cheese_wheels` is `cultures`. The junction is *also* exposed as a plain
+  hasMany (`wheelCultures`), and picking that one gives junction rows rather
+  than the entities you wanted.
+
+If a `turbine mcp` server is connected, `relation_graph` lists these names
+exactly, and `find_join_path` returns the `with` clause to write. Read them
+rather than deriving them.
+
+## 3. Either spelling of a name works, and results are always camelCase
+
+A column or relation may be written in the schema's `snake_case` or in the
+generated `camelCase`, in every argument position, and the two produce identical
+SQL. Results are always camelCase: `cave_humidity_pct` comes back as
+`caveHumidityPct`.
+
+Prefer camelCase, because that is what the generated types autocomplete and what
+you will read back. A name that is neither spelling is a `ValidationError`
+(`TURBINE_E003`) for a column, `RelationError` (`TURBINE_E005`) for a relation,
+and the message suggests the closest real name.
+
+## 4. `select` is columns only
+
+`select` and `omit` name columns. Naming a relation in `select` throws
+`TURBINE_E003` pointing at `with`; relations carry their own nested `select`.
+`select` and `omit` together throw, and so does a `select` that names no field.
+
+## Reads
+
+| method | returns |
+|---|---|
+| `findMany` | `T[]` |
+| `findFirst` / `findFirstOrThrow` | the first row matching an optional filter |
+| `findUnique` / `findUniqueOrThrow` | one row addressed by a unique key |
+| `count` | a `number` |
+| `aggregate` | one row of aggregates |
+| `groupBy` | one row per group |
+
+`findUnique` requires a `where` that identifies a single row: a primary key, a
+single-column unique, or every column of a compound unique. Anything else is
+`TURBINE_E003` naming the keys that would work. Use `findFirst` for "any row
+matching a filter", and give it an `orderBy` if you care which one.
+
+## WHERE
+
+A bare value means equality; `null` means `IS NULL`.
+
+```ts
+where: {
+  status: 'graded',
+  retiredAt: null,
+  caveHumidityPct: { gte: 90, lte: 94 },
+  rindStyle: { in: ['washed', 'waxed'] },
+  givenName: { contains: 'Roux', mode: 'insensitive' },
+  batchRef: { startsWith: 'WB-' },
+  wheelCount: { not: 0 },
+}
+```
+
+Operators: `equals`, `not`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `contains`,
+`startsWith`, `endsWith`, plus `mode: 'insensitive'`. `AND`, `OR` and `NOT` nest
+at any depth; `AND` and `OR` take arrays.
+
+Values are always bound as parameters, and `contains` / `startsWith` /
+`endsWith` escape LIKE wildcards for you. There is no code path in the typed API
+that concatenates a value into SQL.
+
+## Relation filters: `some` / `none` / `every`
+
+Filter parents by their children without returning the children:
+
+```ts
+where: { cheeseWheels: { some: { status: 'quarantined' } } }
+where: { ripeningChecks: { none: {} } }          // has no rows at all
+where: { cheeseWheels: { every: { caveHumidityPct: { gte: 85 } } } }
+```
+
+These are filters, not projections: they add nothing to the result. To get the
+children too, add a `with`.
+
+## Per-relation options
+
+Everything inside a `with` applies PER PARENT ROW, so `limit: 3` means three
+children each, not three overall.
+
+```ts
+with: {
+  affineurs: {
+    select: { id: true },
+    where: { isJourneyman: true },
+    orderBy: { id: 'desc' },
+    limit: 3,
+    with: { cheeseWheels: { select: { id: true } } },   // nests to any depth
+  },
+}
+```
+
+## Ordering
+
+`orderBy` takes an object or an array of objects; an array keeps its order as
+tie breakers. Two special forms:
+
+```ts
+orderBy: [{ pressedOn: 'desc' }, { id: 'desc' }]
+orderBy: { affineurs: { _count: 'desc' } }
+orderBy: { tastingNotes: { path: ['panel', 'score'], direction: 'desc' } }
+```
+
+Without an `orderBy`, row order is undefined. A paginated query with no
+`orderBy` is not just unordered, it is unstable: the same row can appear on two
+pages or on none. Turbine warns about it in development.
+
+## Pagination
+
+`limit` and `offset`, with Prisma's `take` and `skip` accepted as aliases for
+them. Passing both spellings of one bound with different values throws.
+
+```ts
+{ limit: 20, offset: 40 }      // the same query, written two ways
+{ take: 20, skip: 40 }
+```
+
+For deep pages, prefer a `cursor` over a large `offset`.
+
+## JSON columns
+
+A `path` array walks the document, and combines with the normal operators:
+
+```ts
+where: { tastingNotes: { path: ['panel', 'score'], gte: 9 } }
+where: { credentialBlob: { path: ['tier'], equals: 'master' } }
+```
+
+A path takes a NARROWER operator set than a plain column: `equals`, `gt`, `gte`,
+`lt`, `lte`, `contains`, `startsWith`, `endsWith`, plus `mode`. `not`, `in` and
+`notIn` are refused with `TURBINE_E003` listing what is accepted; express them
+with `NOT` / `OR` around the path filter instead.
+
+`_count` accepts a JSON path, and `groupBy` accepts one as a grouping key via
+`{ field, path }`. **`_avg`, `_sum`, `_min` and `_max` do not work on a JSON
+path**: they reach the database as `avg(jsonb)` and fail there. Cast the value
+into a real column, or aggregate in application code.
+
+## Aggregates
+
+```ts
+await db.ripeningChecks.aggregate({
+  where: { rindScore: { gte: 8 } },
+  _avg: { aromaScore: true },
+  _max: { aromaScore: true },
+  _count: { id: true },
+});
+```
+
+## groupBy and having
+
+`by` lists the grouping columns. The `having` shape is **column first, aggregate
+second**, which is the opposite of how it reads aloud:
+
+```ts
+await db.cheeseWheels.groupBy({
+  by: ['rindStyle'],
+  _count: { id: true },
+  having: { id: { _count: { gt: 55 } } },
+  orderBy: { rindStyle: 'asc' },
+});
+```
+
+`having: { wheelCount: { _sum: { gt: 400 } } }` filters on a summed column. The
+column named in `having` must be one you grouped by or aggregated.
+
+## Unique lookups
+
+For a single-column unique, name the column. For a compound unique, use the
+joined selector whose value is an object of the parts, or pass the columns flat:
+
+```ts
+where: { guildId_batchRef: { guildId: 4, batchRef: 'WB-0007' } }
+where: { guildId: 4, batchRef: 'WB-0007' }              // equivalent
+```
+
+## `distinct`
+
+`distinct: ['status']` de-duplicates on those columns.
+
+## Errors worth branching on
+
+Every error extends `TurbineError` and carries a stable `code`. The ones a query
+produces:
+
+| code | class | means |
+|---|---|---|
+| `TURBINE_E003` | `ValidationError` | unknown column, bad operator, refused shape |
+| `TURBINE_E005` | `RelationError` | unknown relation name in `with` |
+| `TURBINE_E001` | `NotFoundError` | an `*OrThrow` matched nothing |
+| `TURBINE_E008` | `UniqueConstraintError` | a write hit a unique constraint |
+
+Branch on the class or the code, never on the message text: messages are not
+covered by semver, and every message carries a link to its docs page.
+
+## Before you answer
+
+- Did the task ask for a relation? Then it is `with`, not `include`, and not
+  `select`.
+- Did it name exact columns? Then `select` exactly those and no more.
+- Did it ask for an order? Then `orderBy` it explicitly.
+- Did it ask for a count rather than rows? Then `count`, not `findMany`.
+- Are you looking a row up by something that is not a unique key? Then
+  `findFirst`, not `findUnique`.