v2.16.2: Add raw-prepend planner hints; fix upsert() rows order bug

Author: dimikot

docs/classes/AllowIf.md

@@ -35,7 +35,7 @@ Defined in: [src/ent/rules/Rule.ts:43](https://github.com/clickup/ent-framework/
 
 | Parameter | Type |
 | ------ | ------ |
-| `predicate` | [`Predicate`](../interfaces/Predicate.md)\<`TInput`\> \| (`vc`, `input`) => `Promise`\<`boolean`\> |
+| `predicate` | [`Predicate`](../interfaces/Predicate.md)\<`TInput`\> \| (`vc`, `input`) => `boolean` \| `Promise`\<`boolean`\> |
 
 #### Returns
 

docs/classes/Batcher.md

@@ -27,7 +27,7 @@ Batcher is similar to DataLoader, but with a few important differences:
 
 ### new Batcher()
 
-> **new Batcher**\<`TInput`, `TOutput`\>(`runner`, `batchDelayMs`): [`Batcher`](Batcher.md)\<`TInput`, `TOutput`\>
+> **new Batcher**\<`TInput`, `TOutput`\>(`runner`, `batchDelayMs`, `disableBatching`): [`Batcher`](Batcher.md)\<`TInput`, `TOutput`\>
 
 Defined in: [src/abstract/Batcher.ts:90](https://github.com/clickup/ent-framework/blob/master/src/abstract/Batcher.ts#L90)
 
@@ -37,6 +37,7 @@ Defined in: [src/abstract/Batcher.ts:90](https://github.com/clickup/ent-framewor
 | ------ | ------ |
 | `runner` | [`Runner`](Runner.md)\<`TInput`, `TOutput`\> |
 | `batchDelayMs` | `MaybeCallable`\<`number`\> |
+| `disableBatching` | `boolean` |
 
 #### Returns
 
@@ -60,7 +61,7 @@ Defined in: [src/abstract/Batcher.ts:32](https://github.com/clickup/ent-framewor
 
 > **run**(`input`, `annotation`): `Promise`\<`TOutput`\>
 
-Defined in: [src/abstract/Batcher.ts:95](https://github.com/clickup/ent-framework/blob/master/src/abstract/Batcher.ts#L95)
+Defined in: [src/abstract/Batcher.ts:96](https://github.com/clickup/ent-framework/blob/master/src/abstract/Batcher.ts#L96)
 
 #### Parameters
 

docs/classes/Client.md

@@ -227,19 +227,22 @@ Calls swallowedErrorLogger() doing some preliminary amendment.
 
 ### batcher()
 
-> **batcher**\<`TInput`, `TOutput`, `TTable`\>(`_QueryClass`, `_schema`, `_additionalShape`, `runnerCreator`): [`Batcher`](Batcher.md)\<`TInput`, `TOutput`\>
+> **batcher**\<`TInput`, `TOutput`, `TTable`\>(`_QueryClass`, `_schema`, `_additionalShape`, `disableBatching`, `runnerCreator`): [`Batcher`](Batcher.md)\<`TInput`, `TOutput`\>
 
-Defined in: [src/abstract/Client.ts:179](https://github.com/clickup/ent-framework/blob/master/src/abstract/Client.ts#L179)
+Defined in: [src/abstract/Client.ts:182](https://github.com/clickup/ent-framework/blob/master/src/abstract/Client.ts#L182)
+
+Batcher is per-Client per-query-type
+per-table-name-and-shape-and-disableBatching:
 
-Batcher is per-Client per-query-type per-table-name-and-shape:
 - Per-Client means that batchers are removed as soon as the Client is
   removed, i.e. the Client owns all the batchers for all tables.
 - Per-query-type means that the batcher for a SELECT query is different
   from the batcher for an INSERT query (obviously).
-- Per-table-name-and-shape means that each table has its own set of
-  batchers (obviously). Also, some queries may be complex (like UPDATE), so
-  the batcher also depends on the "shape" - the list of fields we're
-  updating.
+- Per-table-name-and-shape-and-disableBatching means that each table has
+  its own set of batchers (obviously). Also, some queries may be complex
+  (like UPDATE), so the batcher also depends on the "shape" - the list of
+  fields we're updating. Plus, for some inputs, we want to disable batching
+  at all - that produces a separate Batcher instance.
 
 Also, for every Batcher, there is exactly one Runner (which knows how to
 build the actual query in the context of the current Client). Batchers are
@@ -264,6 +267,7 @@ All that means that in a 1000-Shard 20-table Cluster we'll eventually have
 | `_QueryClass` | `Function` |
 | `_schema` | [`Schema`](Schema.md)\<`TTable`, [`UniqueKey`](../type-aliases/UniqueKey.md)\<`TTable`\>\> |
 | `_additionalShape` | `string` |
+| `disableBatching` | `boolean` |
 | `runnerCreator` | () => [`Runner`](Runner.md)\<`TInput`, `TOutput`\> |
 
 #### Returns
@@ -276,7 +280,7 @@ All that means that in a 1000-Shard 20-table Cluster we'll eventually have
 
 > **prewarm**(): `void`
 
-Defined in: [src/abstract/Client.ts:199](https://github.com/clickup/ent-framework/blob/master/src/abstract/Client.ts#L199)
+Defined in: [src/abstract/Client.ts:207](https://github.com/clickup/ent-framework/blob/master/src/abstract/Client.ts#L207)
 
 A convenience method to put connections prewarming logic to. The idea is to
 keep the needed number of open connections and also, in each connection,

docs/classes/DenyIf.md

@@ -37,7 +37,7 @@ Defined in: [src/ent/rules/Rule.ts:43](https://github.com/clickup/ent-framework/
 
 | Parameter | Type |
 | ------ | ------ |
-| `predicate` | [`Predicate`](../interfaces/Predicate.md)\<`TInput`\> \| (`vc`, `input`) => `Promise`\<`boolean`\> |
+| `predicate` | [`Predicate`](../interfaces/Predicate.md)\<`TInput`\> \| (`vc`, `input`) => `boolean` \| `Promise`\<`boolean`\> |
 
 #### Returns
 

docs/classes/Or.md

@@ -32,7 +32,7 @@ Defined in: [src/ent/predicates/Or.ts:14](https://github.com/clickup/ent-framewo
 
 | Parameter | Type |
 | ------ | ------ |
-| ...`predicates` | readonly ([`Predicate`](../interfaces/Predicate.md)\<`TInput`\> \| (`vc`, `input`) => `Promise`\<`boolean`\>)[] |
+| ...`predicates` | readonly ([`Predicate`](../interfaces/Predicate.md)\<`TInput`\> \| (`vc`, `input`) => `boolean` \| `Promise`\<`boolean`\>)[] |
 
 #### Returns
 
@@ -51,7 +51,7 @@ Defined in: [src/ent/predicates/Or.ts:14](https://github.com/clickup/ent-framewo
 
 > **check**(`vc`, `input`): `Promise`\<`boolean`\>
 
-Defined in: [src/ent/predicates/Or.ts:26](https://github.com/clickup/ent-framework/blob/master/src/ent/predicates/Or.ts#L26)
+Defined in: [src/ent/predicates/Or.ts:27](https://github.com/clickup/ent-framework/blob/master/src/ent/predicates/Or.ts#L27)
 
 #### Parameters
 

docs/classes/PgClient.md

@@ -149,19 +149,22 @@ Calls swallowedErrorLogger() doing some preliminary amendment.
 
 ### batcher()
 
-> **batcher**\<`TInput`, `TOutput`, `TTable`\>(`_QueryClass`, `_schema`, `_additionalShape`, `runnerCreator`): [`Batcher`](Batcher.md)\<`TInput`, `TOutput`\>
+> **batcher**\<`TInput`, `TOutput`, `TTable`\>(`_QueryClass`, `_schema`, `_additionalShape`, `disableBatching`, `runnerCreator`): [`Batcher`](Batcher.md)\<`TInput`, `TOutput`\>
 
-Defined in: [src/abstract/Client.ts:179](https://github.com/clickup/ent-framework/blob/master/src/abstract/Client.ts#L179)
+Defined in: [src/abstract/Client.ts:182](https://github.com/clickup/ent-framework/blob/master/src/abstract/Client.ts#L182)
+
+Batcher is per-Client per-query-type
+per-table-name-and-shape-and-disableBatching:
 
-Batcher is per-Client per-query-type per-table-name-and-shape:
 - Per-Client means that batchers are removed as soon as the Client is
   removed, i.e. the Client owns all the batchers for all tables.
 - Per-query-type means that the batcher for a SELECT query is different
   from the batcher for an INSERT query (obviously).
-- Per-table-name-and-shape means that each table has its own set of
-  batchers (obviously). Also, some queries may be complex (like UPDATE), so
-  the batcher also depends on the "shape" - the list of fields we're
-  updating.
+- Per-table-name-and-shape-and-disableBatching means that each table has
+  its own set of batchers (obviously). Also, some queries may be complex
+  (like UPDATE), so the batcher also depends on the "shape" - the list of
+  fields we're updating. Plus, for some inputs, we want to disable batching
+  at all - that produces a separate Batcher instance.
 
 Also, for every Batcher, there is exactly one Runner (which knows how to
 build the actual query in the context of the current Client). Batchers are
@@ -186,6 +189,7 @@ All that means that in a 1000-Shard 20-table Cluster we'll eventually have
 | `_QueryClass` | `Function` |
 | `_schema` | [`Schema`](Schema.md)\<`TTable`, [`UniqueKey`](../type-aliases/UniqueKey.md)\<`TTable`\>\> |
 | `_additionalShape` | `string` |
+| `disableBatching` | `boolean` |
 | `runnerCreator` | () => [`Runner`](Runner.md)\<`TInput`, `TOutput`\> |
 
 #### Returns
@@ -202,7 +206,7 @@ All that means that in a 1000-Shard 20-table Cluster we'll eventually have
 
 > **prewarm**(): `void`
 
-Defined in: [src/abstract/Client.ts:199](https://github.com/clickup/ent-framework/blob/master/src/abstract/Client.ts#L199)
+Defined in: [src/abstract/Client.ts:207](https://github.com/clickup/ent-framework/blob/master/src/abstract/Client.ts#L207)
 
 A convenience method to put connections prewarming logic to. The idea is to
 keep the needed number of open connections and also, in each connection,
@@ -305,7 +309,7 @@ should expect that role() returns the actual master/replica role.
 
 > **shardNos**(): `Promise`\<readonly `number`[]\>
 
-Defined in: [src/pg/PgClient.ts:402](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L402)
+Defined in: [src/pg/PgClient.ts:408](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L408)
 
 Returns all Shard numbers discoverable via the connection to the Client's
 database.
@@ -324,7 +328,7 @@ database.
 
 > **ping**(`__namedParameters`): `Promise`\<`void`\>
 
-Defined in: [src/pg/PgClient.ts:426](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L426)
+Defined in: [src/pg/PgClient.ts:432](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L432)
 
 Sends a read or write test query to the server. Tells the server to sit and
 wait for at least the provided number of milliseconds.
@@ -349,7 +353,7 @@ wait for at least the provided number of milliseconds.
 
 > **shardNoByID**(`id`): `number`
 
-Defined in: [src/pg/PgClient.ts:444](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L444)
+Defined in: [src/pg/PgClient.ts:450](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L450)
 
 Extracts Shard number from an ID.
 
@@ -373,7 +377,7 @@ Extracts Shard number from an ID.
 
 > **withShard**(`no`): `this`
 
-Defined in: [src/pg/PgClient.ts:500](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L500)
+Defined in: [src/pg/PgClient.ts:506](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L506)
 
 Creates a new Client which is namespaced to the provided Shard number. The
 new Client will share the same connection pool with the parent's Client.
@@ -398,7 +402,7 @@ new Client will share the same connection pool with the parent's Client.
 
 > **role**(): [`ClientRole`](../type-aliases/ClientRole.md)
 
-Defined in: [src/pg/PgClient.ts:511](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L511)
+Defined in: [src/pg/PgClient.ts:517](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L517)
 
 Returns the Client's role reported after the last successful query. Master
 and replica roles may switch online unpredictably, without reconnecting, so
@@ -418,7 +422,7 @@ we only know the role after a query.
 
 > **connectionIssue**(): `null` \| [`ClientConnectionIssue`](../interfaces/ClientConnectionIssue.md)
 
-Defined in: [src/pg/PgClient.ts:515](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L515)
+Defined in: [src/pg/PgClient.ts:521](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L521)
 
 Returns a non-nullable value if the Client couldn't connect to the server
 (or it could, but the load balancer reported the remote server as not

docs/classes/PgClientPool.md

@@ -54,19 +54,22 @@ Defined in: [src/pg/PgClientPool.ts:75](https://github.com/clickup/ent-framework
 
 ### batcher()
 
-> **batcher**\<`TInput`, `TOutput`, `TTable`\>(`_QueryClass`, `_schema`, `_additionalShape`, `runnerCreator`): [`Batcher`](Batcher.md)\<`TInput`, `TOutput`\>
+> **batcher**\<`TInput`, `TOutput`, `TTable`\>(`_QueryClass`, `_schema`, `_additionalShape`, `disableBatching`, `runnerCreator`): [`Batcher`](Batcher.md)\<`TInput`, `TOutput`\>
 
-Defined in: [src/abstract/Client.ts:179](https://github.com/clickup/ent-framework/blob/master/src/abstract/Client.ts#L179)
+Defined in: [src/abstract/Client.ts:182](https://github.com/clickup/ent-framework/blob/master/src/abstract/Client.ts#L182)
+
+Batcher is per-Client per-query-type
+per-table-name-and-shape-and-disableBatching:
 
-Batcher is per-Client per-query-type per-table-name-and-shape:
 - Per-Client means that batchers are removed as soon as the Client is
   removed, i.e. the Client owns all the batchers for all tables.
 - Per-query-type means that the batcher for a SELECT query is different
   from the batcher for an INSERT query (obviously).
-- Per-table-name-and-shape means that each table has its own set of
-  batchers (obviously). Also, some queries may be complex (like UPDATE), so
-  the batcher also depends on the "shape" - the list of fields we're
-  updating.
+- Per-table-name-and-shape-and-disableBatching means that each table has
+  its own set of batchers (obviously). Also, some queries may be complex
+  (like UPDATE), so the batcher also depends on the "shape" - the list of
+  fields we're updating. Plus, for some inputs, we want to disable batching
+  at all - that produces a separate Batcher instance.
 
 Also, for every Batcher, there is exactly one Runner (which knows how to
 build the actual query in the context of the current Client). Batchers are
@@ -91,6 +94,7 @@ All that means that in a 1000-Shard 20-table Cluster we'll eventually have
 | `_QueryClass` | `Function` |
 | `_schema` | [`Schema`](Schema.md)\<`TTable`, [`UniqueKey`](../type-aliases/UniqueKey.md)\<`TTable`\>\> |
 | `_additionalShape` | `string` |
+| `disableBatching` | `boolean` |
 | `runnerCreator` | () => [`Runner`](Runner.md)\<`TInput`, `TOutput`\> |
 
 #### Returns
@@ -145,7 +149,7 @@ should expect that role() returns the actual master/replica role.
 
 > **shardNos**(): `Promise`\<readonly `number`[]\>
 
-Defined in: [src/pg/PgClient.ts:402](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L402)
+Defined in: [src/pg/PgClient.ts:408](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L408)
 
 Returns all Shard numbers discoverable via the connection to the Client's
 database.
@@ -164,7 +168,7 @@ database.
 
 > **ping**(`__namedParameters`): `Promise`\<`void`\>
 
-Defined in: [src/pg/PgClient.ts:426](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L426)
+Defined in: [src/pg/PgClient.ts:432](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L432)
 
 Sends a read or write test query to the server. Tells the server to sit and
 wait for at least the provided number of milliseconds.
@@ -189,7 +193,7 @@ wait for at least the provided number of milliseconds.
 
 > **shardNoByID**(`id`): `number`
 
-Defined in: [src/pg/PgClient.ts:444](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L444)
+Defined in: [src/pg/PgClient.ts:450](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L450)
 
 Extracts Shard number from an ID.
 
@@ -213,7 +217,7 @@ Extracts Shard number from an ID.
 
 > **withShard**(`no`): `this`
 
-Defined in: [src/pg/PgClient.ts:500](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L500)
+Defined in: [src/pg/PgClient.ts:506](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L506)
 
 Creates a new Client which is namespaced to the provided Shard number. The
 new Client will share the same connection pool with the parent's Client.
@@ -238,7 +242,7 @@ new Client will share the same connection pool with the parent's Client.
 
 > **role**(): [`ClientRole`](../type-aliases/ClientRole.md)
 
-Defined in: [src/pg/PgClient.ts:511](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L511)
+Defined in: [src/pg/PgClient.ts:517](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L517)
 
 Returns the Client's role reported after the last successful query. Master
 and replica roles may switch online unpredictably, without reconnecting, so
@@ -258,7 +262,7 @@ we only know the role after a query.
 
 > **connectionIssue**(): `null` \| [`ClientConnectionIssue`](../interfaces/ClientConnectionIssue.md)
 
-Defined in: [src/pg/PgClient.ts:515](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L515)
+Defined in: [src/pg/PgClient.ts:521](https://github.com/clickup/ent-framework/blob/master/src/pg/PgClient.ts#L521)
 
 Returns a non-nullable value if the Client couldn't connect to the server
 (or it could, but the load balancer reported the remote server as not

docs/classes/PgQuerySelect.md

@@ -6,7 +6,7 @@
 
 # Class: PgQuerySelect\<TTable\>
 
-Defined in: [src/pg/PgQuerySelect.ts:12](https://github.com/clickup/ent-framework/blob/master/src/pg/PgQuerySelect.ts#L12)
+Defined in: [src/pg/PgQuerySelect.ts:35](https://github.com/clickup/ent-framework/blob/master/src/pg/PgQuerySelect.ts#L35)
 
 A convenient base class for most (but not all) of the queries, where the
 Runner instance is the same for different query input shapes. If the query
@@ -78,7 +78,7 @@ Defined in: [src/abstract/QueryBase.ts:33](https://github.com/clickup/ent-framew
 
 > **run**(`client`, `annotation`): `Promise`\<[`Row`](../type-aliases/Row.md)\<`TTable`\>[]\>
 
-Defined in: [src/abstract/QueryBase.ts:37](https://github.com/clickup/ent-framework/blob/master/src/abstract/QueryBase.ts#L37)
+Defined in: [src/pg/PgQuerySelect.ts:44](https://github.com/clickup/ent-framework/blob/master/src/pg/PgQuerySelect.ts#L44)
 
 #### Parameters
 
@@ -91,6 +91,6 @@ Defined in: [src/abstract/QueryBase.ts:37](https://github.com/clickup/ent-framew
 
 `Promise`\<[`Row`](../type-aliases/Row.md)\<`TTable`\>[]\>
 
-#### Inherited from
+#### Overrides
 
 [`QueryBase`](QueryBase.md).[`run`](QueryBase.md#run)

docs/classes/PgRunner.md

@@ -94,9 +94,10 @@ one input to process, not many.
 
 > `abstract` `optional` **runBatch**(`inputs`, `annotations`): `Promise`\<`Map`\<`string`, `TOutput`\>\>
 
-Defined in: [src/abstract/Runner.ts:38](https://github.com/clickup/ent-framework/blob/master/src/abstract/Runner.ts#L38)
+Defined in: [src/abstract/Runner.ts:39](https://github.com/clickup/ent-framework/blob/master/src/abstract/Runner.ts#L39)
 
-Typically issues complex queries with magic.
+Typically issues complex queries with magic. If the method is not defined,
+then the runner doesn't support batching, so only runSingle() will be used.
 
 #### Parameters
 
@@ -119,7 +120,7 @@ Typically issues complex queries with magic.
 
 > **key**(`_input`): `string`
 
-Defined in: [src/abstract/Runner.ts:76](https://github.com/clickup/ent-framework/blob/master/src/abstract/Runner.ts#L76)
+Defined in: [src/abstract/Runner.ts:77](https://github.com/clickup/ent-framework/blob/master/src/abstract/Runner.ts#L77)
 
 Returns a batch-dedupping key for the input. By default, no dedupping is
 performed (i.e. all inputs are processed individually and not collapsed

docs/classes/Require.md

@@ -35,7 +35,7 @@ Defined in: [src/ent/rules/Rule.ts:43](https://github.com/clickup/ent-framework/
 
 | Parameter | Type |
 | ------ | ------ |
-| `predicate` | [`Predicate`](../interfaces/Predicate.md)\<`TInput`\> \| (`vc`, `input`) => `Promise`\<`boolean`\> |
+| `predicate` | [`Predicate`](../interfaces/Predicate.md)\<`TInput`\> \| (`vc`, `input`) => `boolean` \| `Promise`\<`boolean`\> |
 
 #### Returns