turbine-orm 0.50.0 → 0.51.0

package/dist/cjs/cli/ui.d.ts

@@ -1,8 +1,8 @@
 /**
- * turbine-orm CLI — UI utilities
+ * turbine-orm CLI, UI utilities
  *
  * ANSI colors, spinners, box-drawing, and formatting helpers.
- * Zero dependencies — raw escape codes only.
+ * Zero dependencies, raw escape codes only.
  */
 export declare const bold: (s: string) => string;
 export declare const dim: (s: string) => string;

package/dist/cjs/cli/ui.js

@@ -1,9 +1,9 @@
 "use strict";
 /**
- * turbine-orm CLI — UI utilities
+ * turbine-orm CLI, UI utilities
  *
  * ANSI colors, spinners, box-drawing, and formatting helpers.
- * Zero dependencies — raw escape codes only.
+ * Zero dependencies, raw escape codes only.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Spinner = exports.symbols = exports.bgCyan = exports.bgYellow = exports.bgRed = exports.bgGreen = exports.redBright = exports.yellowBright = exports.cyanBright = exports.greenBright = exports.gray = exports.white = exports.cyan = exports.magenta = exports.blue = exports.yellow = exports.green = exports.red = exports.underline = exports.italic = exports.dim = exports.bold = void 0;

package/dist/cjs/client.d.ts

@@ -1,5 +1,5 @@
 /**
- * turbine-orm — TurbineClient
+ * turbine-orm, TurbineClient
  *
  * The main entry point for the Turbine TypeScript SDK.
  * Manages connection pooling and provides typed table accessors.
@@ -84,7 +84,7 @@ export interface PgCompatPoolClient {
 }
 /**
  * Minimal pg-compatible pool. Pass any driver that satisfies this interface
- * via `TurbineConfig.pool` — lets Turbine run on Neon HTTP, Vercel Postgres,
+ * via `TurbineConfig.pool`, lets Turbine run on Neon HTTP, Vercel Postgres,
  * Cloudflare Hyperdrive, or any other serverless Postgres driver.
  *
  * @example
@@ -100,16 +100,16 @@ export interface PgCompatPool {
     query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<PgCompatQueryResult<R>>;
     connect(): Promise<PgCompatPoolClient>;
     end(): Promise<void>;
-    /** Optional — pools that expose stats (pg.Pool does; Neon HTTP does not) */
+    /** Optional, pools that expose stats (pg.Pool does; Neon HTTP does not) */
     readonly totalCount?: number;
     readonly idleCount?: number;
     readonly waitingCount?: number;
-    /** Optional — pg.Pool supports 'error' event; HTTP drivers typically do not */
+    /** Optional, pg.Pool supports 'error' event; HTTP drivers typically do not */
     on?(event: 'error', listener: (err: Error) => void): this;
 }
 /**
  * Driver-neutral seam. Bundles a pg-compatible connection pool with the SQL
- * {@link Dialect} that owns every piece of SQL text varying across engines —
+ * {@link Dialect} that owns every piece of SQL text varying across engines -
  * parameter placeholders, transaction-control keywords (BEGIN/COMMIT/ROLLBACK/
  * SAVEPOINT/isolation/set_config), streaming, and capability flags.
  *
@@ -175,7 +175,7 @@ export interface TurbineConfig {
      */
     warnOnUnlimited?: boolean | Record<string, boolean>;
     /**
-     * Interpret Postgres `timestamp` (without time zone) values as UTC — both
+     * Interpret Postgres `timestamp` (without time zone) values as UTC, both
      * at the driver level (OID 1114 type parser, registered only when Turbine
      * owns the pool) and when coercing nested-relation JSON dates. This is the
      * Prisma/Rails/Django convention and makes results independent of the
@@ -183,6 +183,17 @@ export interface TurbineConfig {
      * local-time interpretation.
      */
     utcTimestamps?: boolean;
+    /**
+     * Refuse a nested `connect` / `connectOrCreate` that would re-parent a
+     * to-many child already owned by a different parent. Off by default,
+     * because it changes the outcome of writes that currently succeed.
+     *
+     * Worth turning on for any multi-tenant application: without it, a handler
+     * that forwards a client-supplied id into a nested connect lets a caller
+     * take another tenant's row. See
+     * {@link import('./nested-write.js').NestedWriteContext.scopedConnect}.
+     */
+    scopedConnect?: boolean;
     /**
      * Default strategy for resolving `with`-clause relations, applied to every
      * `findMany`/`findUnique`/`findFirst` unless overridden per query.
@@ -259,9 +270,9 @@ export interface TurbineConfig {
     /**
      * How nested-relation subqueries encode each row's JSON.
      *
-     *   - `'object'` (default) — `json_agg(json_build_object('key', v, …))`. Every
+     *   - `'object'` (default), `json_agg(json_build_object('key', v, …))`. Every
      *     key name is repeated in every nested object of every row.
-     *   - `'positional'` — `json_agg(json_build_array(v, …))`. Turbine knows the
+     *   - `'positional'`, `json_agg(json_build_array(v, …))`. Turbine knows the
      *     column order at build time, so it emits a key-less array and maps
      *     positions back to keys client-side. Same information, a fraction of the
      *     bytes on wide/deeply-nested `with` trees. Parsed output is byte-identical
@@ -323,16 +334,16 @@ export interface TurbineConfig {
      * `$transaction` bodies, `pipeline`, `raw`/`sql`, `$listen`/`$notify`, and
      * observability flushes always use the primary.
      *
-     *   - `string` entries are connection strings — Turbine constructs an owned
+     *   - `string` entries are connection strings, Turbine constructs an owned
      *     `pg.Pool` for each (same pool-tuning knobs as the primary, and the same
      *     one-time, constructor-gated type-parser registration). `disconnect()`
      *     closes them.
      *   - `PgCompatPool` entries are external pools (Neon, Vercel, a shared
-     *     `pg.Pool`) — Turbine registers no type parsers on them and never ends
+     *     `pg.Pool`), Turbine registers no type parsers on them and never ends
      *     them; the caller owns their lifecycle.
      *
      * Use `client.$primary()` to get a view of the client that pins every
-     * operation (reads included) to the primary — e.g. to read your own write
+     * operation (reads included) to the primary, e.g. to read your own write
      * without replication lag. Omitting `replicas` (or passing `[]`) leaves the
      * default single-pool path completely unchanged.
      */
@@ -340,8 +351,8 @@ export interface TurbineConfig {
     /**
      * Automatic WHERE filters applied to every query, keyed by table accessor
      * (`db[name]`). Each value is AND-merged into the compiled WHERE of every
-     * read and mutation on that table — and into every relation subquery that
-     * targets it — implementing soft-delete and multi-tenancy without repeating
+     * read and mutation on that table, and into every relation subquery that
+     * targets it, implementing soft-delete and multi-tenancy without repeating
      * the predicate at each call site.
      *
      *   - A `WhereClause` value is a static filter (e.g. `{ deletedAt: null }`).
@@ -378,7 +389,7 @@ export type MiddlewareNext = (params: MiddlewareParams) => Promise<unknown>;
 /** A middleware function that intercepts queries */
 export type Middleware = (params: MiddlewareParams, next: MiddlewareNext) => Promise<unknown>;
 export interface TransactionOptions {
-    /** Timeout in ms — transaction will be rolled back if exceeded */
+    /** Timeout in ms, transaction will be rolled back if exceeded */
     timeout?: number;
     /** Isolation level for the transaction */
     isolationLevel?: 'ReadUncommitted' | 'ReadCommitted' | 'RepeatableRead' | 'Serializable';
@@ -388,7 +399,7 @@ export interface TransactionOptions {
      * `current_setting('app.current_tenant')`, and you set that value here so
      * every query inside the transaction sees it.
      *
-     * Each entry is applied via `SELECT set_config($1, $2, true)` — `is_local=true`
+     * Each entry is applied via `SELECT set_config($1, $2, true)`, `is_local=true`
      * scopes the value to this transaction, so it auto-resets on COMMIT/ROLLBACK
      * and never leaks onto the pooled connection. Both the name and value are
      * bound parameters (never interpolated); the GUC name is additionally
@@ -429,7 +440,7 @@ export declare class TransactionClient {
     private readonly sourcePool?;
     private readonly tableCache;
     private savepointCounter;
-    /** Active SQL dialect — owns savepoint keywords and raw-SQL placeholders. */
+    /** Active SQL dialect, owns savepoint keywords and raw-SQL placeholders. */
     private readonly dialect;
     constructor(client: pg.PoolClient, schema: SchemaMetadata, middlewares: Middleware[], queryOptions?: QueryInterfaceOptions | undefined, 
     /**
@@ -471,14 +482,14 @@ export declare class TransactionClient {
     private createTxPool;
 }
 export declare class TurbineClient {
-    /** The underlying pg.Pool — exposed for escape hatches */
+    /** The underlying pg.Pool, exposed for escape hatches */
     readonly pool: pg.Pool;
     /** The schema metadata this client was built from */
     readonly schema: SchemaMetadata;
     private static int8ParserRegistered;
     private static utcTimestampParserRegistered;
     private readonly logging;
-    /** Active SQL dialect — owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
+    /** Active SQL dialect, owns transaction keywords, set_config, raw-SQL placeholders, capability flags. */
     private readonly dialect;
     private readonly tableCache;
     private readonly middlewares;
@@ -487,7 +498,7 @@ export declare class TurbineClient {
     private readonly errorMessagesSafe;
     /** True when Turbine created the pool and is responsible for tearing it down */
     private readonly ownsPool;
-    /** Active LISTEN subscriptions — torn down on disconnect() so it never hangs */
+    /** Active LISTEN subscriptions, torn down on disconnect() so it never hangs */
     private readonly activeSubscriptions;
     /**
      * Read-replica pools in round-robin order. Empty when no replicas are
@@ -514,7 +525,7 @@ export declare class TurbineClient {
      *
      * Middleware can inspect and log query parameters, measure timing, and
      * transform the result returned by `next()`. Note: query SQL is generated
-     * BEFORE middleware runs — `params.args` is a read-only snapshot, and
+     * BEFORE middleware runs, `params.args` is a read-only snapshot, and
      * mutating it does NOT change the executed SQL. Cross-cutting filters
      * (e.g. soft deletes) belong in the query itself: pass an explicit
      * `where: { deletedAt: null }` or wrap the table accessor in a small helper.
@@ -529,7 +540,7 @@ export declare class TurbineClient {
      *   return result;
      * });
      *
-     * // Result transformation middleware — redact a field on the way out
+     * // Result transformation middleware, redact a field on the way out
      * db.$use(async (params, next) => {
      *   const result = await next(params);
      *   if (params.model === 'users' && Array.isArray(result)) {
@@ -546,12 +557,12 @@ export declare class TurbineClient {
     $observe(config: ObserveConfig): Promise<ObserveHandle>;
     /**
      * Get a QueryInterface for a table.
-     * Results are cached — calling `table('users')` twice returns the same instance.
+     * Results are cached, calling `table('users')` twice returns the same instance.
      *
      * When read replicas are configured, this returns a thin routing proxy: the
      * read-only operations in {@link READ_OPERATIONS} are dispatched to a
-     * round-robin replica-bound QueryInterface (so an entire read — base rows and
-     * any batched sub-queries — runs against a single consistent replica), while
+     * round-robin replica-bound QueryInterface (so an entire read, base rows and
+     * any batched sub-queries, runs against a single consistent replica), while
      * writes and every other member fall through to the primary-bound instance.
      * With no replicas the original single-pool instance is returned directly.
      */
@@ -572,7 +583,7 @@ export declare class TurbineClient {
      */
     private createRoutingAccessor;
     /**
-     * Return a view of this client that pins EVERY operation — reads included —
+     * Return a view of this client that pins EVERY operation, reads included -
      * to the primary pool, bypassing replica routing. Use it to read your own
      * write without replication lag, or for any read that must see the latest
      * committed data.
@@ -580,7 +591,7 @@ export declare class TurbineClient {
      * The view shares the primary pool, schema, dialect, query options, and
      * middleware; it owns nothing, so its `disconnect()` is a no-op. When no
      * replicas are configured this simply returns the client itself (already
-     * primary-only). The view is cached — repeated calls return the same instance.
+     * primary-only). The view is cached, repeated calls return the same instance.
      *
      * @example
      * ```ts
@@ -594,8 +605,8 @@ export declare class TurbineClient {
      * Execute multiple queries in a single database round-trip.
      *
      * Two call styles:
-     *   - `db.pipeline(q1, q2, q3)` — rest params (backward-compatible)
-     *   - `db.pipeline([q1, q2, q3], { transactional: false })` — array + options
+     *   - `db.pipeline(q1, q2, q3)`, rest params (backward-compatible)
+     *   - `db.pipeline([q1, q2, q3], { transactional: false })`, array + options
      *
      * On pg.Pool-backed connections with TCP, this uses the real Postgres
      * extended-query pipeline protocol (one TCP flush, one round-trip).
@@ -622,7 +633,7 @@ export declare class TurbineClient {
      */
     raw<T extends Record<string, unknown> = Record<string, unknown>>(strings: TemplateStringsArray, ...values: unknown[]): Promise<T[]>;
     /**
-     * Execute a **typed** raw SQL query — Turbine's answer to Prisma's TypedSQL.
+     * Execute a **typed** raw SQL query, Turbine's answer to Prisma's TypedSQL.
      *
      * Like {@link raw}, every interpolated `${value}` becomes a `$N` parameter
      * (never string-concatenated), so it is injection-safe by construction. The
@@ -630,7 +641,7 @@ export declare class TurbineClient {
      * returned {@link TypedSqlQuery} can be `await`ed directly for `T[]`, or
      * refined with `.one()` (→ `T | null`) or `.scalar<V>()` (→ `V | null`).
      *
-     * Rows are returned as-is — no snake→camel mapping (matching `raw()`). Alias
+     * Rows are returned as-is, no snake→camel mapping (matching `raw()`). Alias
      * columns in SQL if you want camelCase keys.
      *
      * @example
@@ -685,7 +696,7 @@ export declare class TurbineClient {
      */
     $transaction<R>(fn: (tx: TransactionClient) => Promise<R>, options?: TransactionOptions): Promise<R>;
     /**
-     * Batch form — run a tuple of {@link DeferredQuery} objects (produced by the
+     * Batch form, run a tuple of {@link DeferredQuery} objects (produced by the
      * `build*()` methods, e.g. `db.users.buildFindMany(...)`) atomically inside a
      * single `BEGIN…COMMIT` on one connection. Returns a positionally-typed tuple
      * of each query's transformed result; any failure rolls the whole batch back.
@@ -693,8 +704,8 @@ export declare class TurbineClient {
      * Unlike {@link pipeline}, this never uses the extended-query pipeline
      * protocol. Statements run on the single transaction connection: strictly
      * sequentially by default (safe on every driver, including HTTP/serverless
-     * pools), or — when the checked-out connection advertises
-     * {@link PgCompatPoolClient.supportsPipelining} — dispatched in one write
+     * pools), or, when the checked-out connection advertises
+     * {@link PgCompatPoolClient.supportsPipelining}, dispatched in one write
      * burst with replies collected in order, saving a network round trip per
      * statement. Either way the failure contract is identical: the first
      * (lowest-index) failure aborts the batch and rolls everything back.
@@ -722,7 +733,7 @@ export declare class TurbineClient {
      *     {@link PgCompatPoolClient.supportsPipelining} (its `query()` accepts
      *     concurrent calls and completes them in FIFO submission order), all
      *     statements are dispatched in one write burst and the replies are
-     *     collected in order — ~1 round trip plus server time. Only taken when
+     *     collected in order, ~1 round trip plus server time. Only taken when
      *     the dialect's writes surface rows directly (`resultStrategy` !==
      *     'reselect'): a reselect plan is itself a sequential write+read pair.
      *
@@ -762,12 +773,12 @@ export declare class TurbineClient {
      *
      * The channel name CANNOT be a bound parameter (`LISTEN $1` is a syntax
      * error), so it is validated against a strict identifier regex AND quoted via
-     * `quoteIdent` before interpolation — it is the only identifier this method
+     * `quoteIdent` before interpolation, it is the only identifier this method
      * places into SQL text.
      *
      * **Serverless caveat:** LISTEN needs a persistent connection that can push
      * async notifications. Stateless HTTP drivers (Neon HTTP, Vercel Postgres)
-     * cannot do this — `$listen` throws a `ConnectionError` rather than hang.
+     * cannot do this, `$listen` throws a `ConnectionError` rather than hang.
      * `$notify` works on every driver.
      *
      * @example
@@ -784,7 +795,7 @@ export declare class TurbineClient {
     /**
      * Send a Postgres NOTIFY on `channel` with an optional payload string.
      *
-     * Issued as `SELECT pg_notify($1, $2)` — both the channel and payload are
+     * Issued as `SELECT pg_notify($1, $2)`, both the channel and payload are
      * BOUND parameters (no quoting/injection concern). The channel is still
      * validated against the identifier regex for parity with `$listen` and to
      * catch typos loudly. Works on every driver, including serverless HTTP pools.
@@ -820,7 +831,7 @@ export declare class TurbineClient {
      * Gracefully shut down the connection pool.
      *
      * If Turbine was given an external pool via `TurbineConfig.pool`, this
-     * method is a no-op — the caller is responsible for the pool's lifecycle.
+     * method is a no-op, the caller is responsible for the pool's lifecycle.
      */
     disconnect(): Promise<void>;
     /** Alias for disconnect() */