turbine-orm 0.81.0 → 0.90.0

package/dist/query/index.d.ts

@@ -8,6 +8,8 @@
 export type { AggregateArgs, AggregateResult, ArrayFilter, ColumnRef, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GlobalFilters, GroupByAggregateSpec, GroupByArgs, GroupByDistinctOn, GroupByResult, HavingClause, JsonEncoding, JsonFilter, JsonPathAggregateTarget, JsonPathGroupKey, JsonPathOrderBy, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderByObject, OrderBySpec, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, RelationOrderBy, RelationOrderByChain, RelationPickBy, RelationPickOrderBy, ResolvedSkipGlobalFilters, SelectResult, SkipGlobalFilters, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithOrderByObject, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
+export { col } from './column-ref.js';
+export { type JsonValue, jsonValue } from './json-value.js';
 export type { OptionKind, OptionTable } from './option-surface.js';
 export { AGGREGATE_OPTIONS, ALL_OPTION_TABLES, applyNativeOptions, COUNT_OPTIONS, CREATE_MANY_OPTIONS, CREATE_OPTIONS, DELETE_MANY_OPTIONS, DELETE_OPTIONS, FIND_MANY_OPTIONS, FIND_MANY_STREAM_OPTIONS, FIND_UNIQUE_OPTIONS, GROUP_BY_OPTIONS, optionKeysOfKind, UPDATE_MANY_OPTIONS, UPDATE_OPTIONS, UPSERT_OPTIONS, } from './option-surface.js';
 export type { PrivilegeOption, Unsafe } from './types.js';

package/dist/query/index.js

@@ -6,6 +6,10 @@
  * former monolithic `import { … } from './query.js'`.
  */
 export { postgresDialect } from '../dialect.js';
+// Column references: `col('field')` builds the branded operand that compares
+// two columns of one row. `jsonValue(v)` marks a value to store as JSON.
+export { col } from './column-ref.js';
+export { jsonValue } from './json-value.js';
 export { AGGREGATE_OPTIONS, ALL_OPTION_TABLES, applyNativeOptions, COUNT_OPTIONS, CREATE_MANY_OPTIONS, CREATE_OPTIONS, DELETE_MANY_OPTIONS, DELETE_OPTIONS, FIND_MANY_OPTIONS, FIND_MANY_STREAM_OPTIONS, FIND_UNIQUE_OPTIONS, GROUP_BY_OPTIONS, optionKeysOfKind, UPDATE_MANY_OPTIONS, UPDATE_OPTIONS, UPSERT_OPTIONS, } from './option-surface.js';
 // The privilege sentinel: a runtime value, not a type (see types.ts).
 export { assertOrderDirection, resolveSkipGlobalFilters, resolveUnsafeFlag, UNSAFE } from './types.js';

package/dist/query/json-value.d.ts

@@ -0,0 +1,43 @@
+/**
+ * turbine-orm: explicit JSON values for json / jsonb writes.
+ *
+ * A JS string written to a json/jsonb column is RAW JSON TEXT: `'{"a":1}'`
+ * stores the object `{ a: 1 }`, which is how `JSON.stringify(value)` callers
+ * have always written documents. That rule leaves no way to store a JSON
+ * STRING (`"hello"`) or a JSON `null` (as opposed to SQL NULL).
+ * `jsonValue(v)` is that way: the wrapped value is serialized with
+ * `JSON.stringify` on every engine and every write path, so
+ *
+ *   jsonValue('hello') stores the JSON string "hello"
+ *   jsonValue(null)    stores the JSON value null (the column is NOT SQL NULL)
+ *   jsonValue([1, 2])  stores the JSON array [1, 2]
+ *
+ * The brand is a `Symbol.for` key so a copy of the package loaded twice (ESM
+ * and CJS) still recognizes the other copy's values, and so `JSON.parse` can
+ * never produce one from request data.
+ */
+declare const JSON_VALUE_BRAND: unique symbol;
+/** A value marked for `JSON.stringify` serialization. Create with {@link jsonValue}. */
+export interface JsonValue<T = unknown> {
+    readonly [JSON_VALUE_BRAND]: true;
+    /** The wrapped value, exactly as passed to {@link jsonValue}. */
+    readonly value: T;
+    /** `JSON.stringify(wrapper)` serializes the wrapped value, never the wrapper. */
+    toJSON(): T;
+}
+/**
+ * Mark `value` to be written as JSON. See the module comment for why a plain
+ * string cannot mean this. Throws (E003 at write time) only when the value is
+ * not JSON-serializable, e.g. a `bigint` or `undefined`.
+ */
+export declare function jsonValue<T>(value: T): JsonValue<T>;
+/** Whether `value` was produced by {@link jsonValue} (any loaded copy of the package). */
+export declare function isJsonValue(value: unknown): value is JsonValue;
+/**
+ * The JSON text a json/jsonb column receives for `value`. `undefined` (and a
+ * function or symbol) has no JSON form and `JSON.stringify` returns
+ * `undefined` for it; a `bigint` makes it throw. Both surface as `undefined`
+ * here so the caller can raise its own E003 naming the column.
+ */
+export declare function serializeJsonValue(value: unknown): string | undefined;
+export {};

package/dist/query/json-value.js

@@ -0,0 +1,54 @@
+/**
+ * turbine-orm: explicit JSON values for json / jsonb writes.
+ *
+ * A JS string written to a json/jsonb column is RAW JSON TEXT: `'{"a":1}'`
+ * stores the object `{ a: 1 }`, which is how `JSON.stringify(value)` callers
+ * have always written documents. That rule leaves no way to store a JSON
+ * STRING (`"hello"`) or a JSON `null` (as opposed to SQL NULL).
+ * `jsonValue(v)` is that way: the wrapped value is serialized with
+ * `JSON.stringify` on every engine and every write path, so
+ *
+ *   jsonValue('hello') stores the JSON string "hello"
+ *   jsonValue(null)    stores the JSON value null (the column is NOT SQL NULL)
+ *   jsonValue([1, 2])  stores the JSON array [1, 2]
+ *
+ * The brand is a `Symbol.for` key so a copy of the package loaded twice (ESM
+ * and CJS) still recognizes the other copy's values, and so `JSON.parse` can
+ * never produce one from request data.
+ */
+const JSON_VALUE_BRAND = Symbol.for('turbine-orm.jsonValue');
+/**
+ * Mark `value` to be written as JSON. See the module comment for why a plain
+ * string cannot mean this. Throws (E003 at write time) only when the value is
+ * not JSON-serializable, e.g. a `bigint` or `undefined`.
+ */
+export function jsonValue(value) {
+    const wrapper = {
+        [JSON_VALUE_BRAND]: true,
+        value,
+        toJSON: () => value,
+        // node-postgres calls `toPostgres` for an object param before its own
+        // JSON fallback; a wrapper that reaches the driver unresolved still binds
+        // the serialized text rather than `{"value":...}`.
+        toPostgres: () => serializeJsonValue(value),
+    };
+    return Object.freeze(wrapper);
+}
+/** Whether `value` was produced by {@link jsonValue} (any loaded copy of the package). */
+export function isJsonValue(value) {
+    return typeof value === 'object' && value !== null && value[JSON_VALUE_BRAND] === true;
+}
+/**
+ * The JSON text a json/jsonb column receives for `value`. `undefined` (and a
+ * function or symbol) has no JSON form and `JSON.stringify` returns
+ * `undefined` for it; a `bigint` makes it throw. Both surface as `undefined`
+ * here so the caller can raise its own E003 naming the column.
+ */
+export function serializeJsonValue(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/query/normalize-args.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `undefined` means absent, decided ONCE at the args seam.
+ *
+ * Every public operation (and its `build*` twin) runs its args through
+ * {@link pruneUndefinedArgs} before anything else reads them: the empty-`where`
+ * guards, the SQL-cache fingerprint, the SQL build and the param collect. A key
+ * whose value is `undefined` is removed, and so is an object (or combinator
+ * array) that BECOMES empty because of it, recursively, so
+ * `{ user: { email: undefined } }` is exactly `{}`. One pass up front, because
+ * consumers that each decide what `undefined` means end up disagreeing: a cache
+ * key that counted `{ gte: undefined }` while the builder skipped it served a
+ * `<=` template to a `>=` call.
+ *
+ * Pruned positions: `where` (combinators, relation filters, column operator
+ * objects including a nested `not`), `having`, `cursor`, `orderBy`, and every
+ * `with` relation's `where` / `orderBy`. Never `data` / `create` / `update`
+ * (a json column may legitimately receive `{}`), never an operand value (an
+ * `in` list, a JSON document, a vector), and never an object written empty
+ * (`{}`, `{ OR: [] }`), which keeps its own meaning. A column operator object
+ * left holding only modifiers (`mode`, `path`, `config`) is removed too:
+ * `{ contains: q, mode: 'insensitive' }` with `q` undefined is no filter.
+ *
+ * PowDB runs the same function from `PowqlInterface.normalizeArgs`, so the
+ * two engines cannot disagree about what `undefined` means.
+ *
+ * @module
+ */
+import type { SchemaMetadata } from '../schema.js';
+/**
+ * Remove every `undefined` from the pruned positions of one operation's args
+ * (see the module comment). Returns `args` by reference when nothing changed.
+ *
+ * `table` is the operation's table; relation filters and `with` levels are
+ * resolved against `schema` so each sub-where is pruned against its own target.
+ */
+export declare function pruneUndefinedArgs<A>(schema: SchemaMetadata, table: string, args: A): A;
+/**
+ * Whether pruning turned a `where` that HAD keys into one with none: every key
+ * the caller wrote was `undefined`. A `where: {}` written as `{}` is not
+ * emptied; it was empty already.
+ */
+export declare function whereEmptiedByPruning(original: unknown, pruned: unknown): boolean;
+/**
+ * Refuse a single-row read whose `where` was emptied by pruning. `findFirst`
+ * with every filter value `undefined` would otherwise return an arbitrary row,
+ * which on a lookup by a secret (a reset token, an invite code) is another
+ * user's row. `findMany` and `count` keep "undefined means absent".
+ */
+export declare function assertWhereNotEmptiedByPruning(table: string, operation: string, original: unknown, pruned: unknown): void;
+/**
+ * THE "has a cursor" test: a plain object holding at least one defined value.
+ * The page-order completion and the cursor planner both ask it (on PowDB too),
+ * so a page cannot be a cursor page to one and not to the other. A `cursor`
+ * written in a shape that names no row never reaches it as "no cursor": see
+ * {@link assertCursorWritten} and {@link assertCursorNotEmptied}.
+ */
+export declare function hasCursor(cursor: unknown): boolean;
+/**
+ * Refuse a `cursor` that is written but names no row: `null`, a value that is
+ * not an object, or `{}`. Read as "no cursor", such a page skipped both the
+ * cursor and the page tiebreaker, so a pager written as
+ * `cursor: last ? { id: last.id } : {}` cut its first page from a different
+ * order than every later page and skipped rows.
+ */
+export declare function assertCursorWritten(table: string, operation: string, cursor: unknown): void;
+/**
+ * Refuse a `cursor` whose every field was `undefined`. Read as absent it would
+ * restart the walk at the first page, so a pager whose last-row value went
+ * missing would re-read page one forever. Same rule and message on every engine.
+ * `operation` names the call in the message when the caller knows it; without
+ * it the message names no operation rather than a wrong one.
+ */
+export declare function assertCursorNotEmptied(table: string, original: unknown, pruned: unknown, operation?: string): void;
+/**
+ * Internal findMany flag: the page STARTS AT the cursor row instead of after
+ * it. Prisma's cursor is inclusive (its `skip: 1` idiom drops the cursor row),
+ * so `turbine-orm/prisma-compat` sets this; core's own `cursor` stays
+ * exclusive. A symbol key, so a request body spread into findMany args cannot
+ * set it (JSON.parse never produces a symbol) and the unknown-option check,
+ * which reads `Object.keys`, never sees it. `Symbol.for` so ESM and CJS copies
+ * of the package agree on it.
+ *
+ * @internal
+ */
+export declare const CURSOR_INCLUSIVE: unique symbol;
+/** Whether `args` carries {@link CURSOR_INCLUSIVE}. @internal */
+export declare function isCursorInclusive(args: unknown): boolean;