camusdb 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +950 -0
  3. package/dist/auth/credentials.d.ts +30 -0
  4. package/dist/auth/credentials.d.ts.map +1 -0
  5. package/dist/auth/credentials.js +23 -0
  6. package/dist/auth/credentials.js.map +1 -0
  7. package/dist/auth/login-client.d.ts +37 -0
  8. package/dist/auth/login-client.d.ts.map +1 -0
  9. package/dist/auth/login-client.js +8 -0
  10. package/dist/auth/login-client.js.map +1 -0
  11. package/dist/auth/rest-login-client.d.ts +17 -0
  12. package/dist/auth/rest-login-client.d.ts.map +1 -0
  13. package/dist/auth/rest-login-client.js +71 -0
  14. package/dist/auth/rest-login-client.js.map +1 -0
  15. package/dist/auth/token-provider.d.ts +123 -0
  16. package/dist/auth/token-provider.d.ts.map +1 -0
  17. package/dist/auth/token-provider.js +209 -0
  18. package/dist/auth/token-provider.js.map +1 -0
  19. package/dist/backup.d.ts +98 -0
  20. package/dist/backup.d.ts.map +1 -0
  21. package/dist/backup.js +153 -0
  22. package/dist/backup.js.map +1 -0
  23. package/dist/cache.d.ts +90 -0
  24. package/dist/cache.d.ts.map +1 -0
  25. package/dist/cache.js +121 -0
  26. package/dist/cache.js.map +1 -0
  27. package/dist/client.d.ts +406 -0
  28. package/dist/client.d.ts.map +1 -0
  29. package/dist/client.js +724 -0
  30. package/dist/client.js.map +1 -0
  31. package/dist/column-type.d.ts +33 -0
  32. package/dist/column-type.d.ts.map +1 -0
  33. package/dist/column-type.js +50 -0
  34. package/dist/column-type.js.map +1 -0
  35. package/dist/column-value.d.ts +77 -0
  36. package/dist/column-value.d.ts.map +1 -0
  37. package/dist/column-value.js +60 -0
  38. package/dist/column-value.js.map +1 -0
  39. package/dist/config.d.ts +181 -0
  40. package/dist/config.d.ts.map +1 -0
  41. package/dist/config.js +315 -0
  42. package/dist/config.js.map +1 -0
  43. package/dist/connection-string.d.ts +45 -0
  44. package/dist/connection-string.d.ts.map +1 -0
  45. package/dist/connection-string.js +170 -0
  46. package/dist/connection-string.js.map +1 -0
  47. package/dist/endpoint-pool.d.ts +70 -0
  48. package/dist/endpoint-pool.d.ts.map +1 -0
  49. package/dist/endpoint-pool.js +120 -0
  50. package/dist/endpoint-pool.js.map +1 -0
  51. package/dist/error-codes.d.ts +44 -0
  52. package/dist/error-codes.d.ts.map +1 -0
  53. package/dist/error-codes.js +43 -0
  54. package/dist/error-codes.js.map +1 -0
  55. package/dist/errors.d.ts +24 -0
  56. package/dist/errors.d.ts.map +1 -0
  57. package/dist/errors.js +33 -0
  58. package/dist/errors.js.map +1 -0
  59. package/dist/hlc.d.ts +19 -0
  60. package/dist/hlc.d.ts.map +1 -0
  61. package/dist/hlc.js +11 -0
  62. package/dist/hlc.js.map +1 -0
  63. package/dist/index.d.ts +55 -0
  64. package/dist/index.d.ts.map +1 -0
  65. package/dist/index.js +51 -0
  66. package/dist/index.js.map +1 -0
  67. package/dist/json.d.ts +41 -0
  68. package/dist/json.d.ts.map +1 -0
  69. package/dist/json.js +345 -0
  70. package/dist/json.js.map +1 -0
  71. package/dist/object-id.d.ts +39 -0
  72. package/dist/object-id.d.ts.map +1 -0
  73. package/dist/object-id.js +99 -0
  74. package/dist/object-id.js.map +1 -0
  75. package/dist/options.d.ts +77 -0
  76. package/dist/options.d.ts.map +1 -0
  77. package/dist/options.js +68 -0
  78. package/dist/options.js.map +1 -0
  79. package/dist/prepared/binder.d.ts +20 -0
  80. package/dist/prepared/binder.d.ts.map +1 -0
  81. package/dist/prepared/binder.js +32 -0
  82. package/dist/prepared/binder.js.map +1 -0
  83. package/dist/prepared/policy.d.ts +81 -0
  84. package/dist/prepared/policy.d.ts.map +1 -0
  85. package/dist/prepared/policy.js +164 -0
  86. package/dist/prepared/policy.js.map +1 -0
  87. package/dist/query-stream.d.ts +55 -0
  88. package/dist/query-stream.d.ts.map +1 -0
  89. package/dist/query-stream.js +94 -0
  90. package/dist/query-stream.js.map +1 -0
  91. package/dist/result-set.d.ts +62 -0
  92. package/dist/result-set.d.ts.map +1 -0
  93. package/dist/result-set.js +100 -0
  94. package/dist/result-set.js.map +1 -0
  95. package/dist/retry.d.ts +38 -0
  96. package/dist/retry.d.ts.map +1 -0
  97. package/dist/retry.js +93 -0
  98. package/dist/retry.js.map +1 -0
  99. package/dist/routing/advice.d.ts +63 -0
  100. package/dist/routing/advice.d.ts.map +1 -0
  101. package/dist/routing/advice.js +61 -0
  102. package/dist/routing/advice.js.map +1 -0
  103. package/dist/routing/route-cache.d.ts +53 -0
  104. package/dist/routing/route-cache.d.ts.map +1 -0
  105. package/dist/routing/route-cache.js +123 -0
  106. package/dist/routing/route-cache.js.map +1 -0
  107. package/dist/routing/router.d.ts +53 -0
  108. package/dist/routing/router.d.ts.map +1 -0
  109. package/dist/routing/router.js +89 -0
  110. package/dist/routing/router.js.map +1 -0
  111. package/dist/row-source.d.ts +48 -0
  112. package/dist/row-source.d.ts.map +1 -0
  113. package/dist/row-source.js +35 -0
  114. package/dist/row-source.js.map +1 -0
  115. package/dist/runtime.d.ts +58 -0
  116. package/dist/runtime.d.ts.map +1 -0
  117. package/dist/runtime.js +137 -0
  118. package/dist/runtime.js.map +1 -0
  119. package/dist/shared-registry.d.ts +32 -0
  120. package/dist/shared-registry.d.ts.map +1 -0
  121. package/dist/shared-registry.js +48 -0
  122. package/dist/shared-registry.js.map +1 -0
  123. package/dist/sql-syntax.d.ts +44 -0
  124. package/dist/sql-syntax.d.ts.map +1 -0
  125. package/dist/sql-syntax.js +83 -0
  126. package/dist/sql-syntax.js.map +1 -0
  127. package/dist/statements.d.ts +15 -0
  128. package/dist/statements.d.ts.map +1 -0
  129. package/dist/statements.js +90 -0
  130. package/dist/statements.js.map +1 -0
  131. package/dist/transaction.d.ts +117 -0
  132. package/dist/transaction.d.ts.map +1 -0
  133. package/dist/transaction.js +204 -0
  134. package/dist/transaction.js.map +1 -0
  135. package/dist/transport/authenticating-transport.d.ts +63 -0
  136. package/dist/transport/authenticating-transport.d.ts.map +1 -0
  137. package/dist/transport/authenticating-transport.js +119 -0
  138. package/dist/transport/authenticating-transport.js.map +1 -0
  139. package/dist/transport/branch-statements.d.ts +39 -0
  140. package/dist/transport/branch-statements.d.ts.map +1 -0
  141. package/dist/transport/branch-statements.js +74 -0
  142. package/dist/transport/branch-statements.js.map +1 -0
  143. package/dist/transport/error-text.d.ts +26 -0
  144. package/dist/transport/error-text.d.ts.map +1 -0
  145. package/dist/transport/error-text.js +75 -0
  146. package/dist/transport/error-text.js.map +1 -0
  147. package/dist/transport/grpc/batcher.d.ts +127 -0
  148. package/dist/transport/grpc/batcher.d.ts.map +1 -0
  149. package/dist/transport/grpc/batcher.js +399 -0
  150. package/dist/transport/grpc/batcher.js.map +1 -0
  151. package/dist/transport/grpc/codec.d.ts +40 -0
  152. package/dist/transport/grpc/codec.d.ts.map +1 -0
  153. package/dist/transport/grpc/codec.js +231 -0
  154. package/dist/transport/grpc/codec.js.map +1 -0
  155. package/dist/transport/grpc/grpc-transport.d.ts +115 -0
  156. package/dist/transport/grpc/grpc-transport.d.ts.map +1 -0
  157. package/dist/transport/grpc/grpc-transport.js +577 -0
  158. package/dist/transport/grpc/grpc-transport.js.map +1 -0
  159. package/dist/transport/grpc/messages.d.ts +221 -0
  160. package/dist/transport/grpc/messages.d.ts.map +1 -0
  161. package/dist/transport/grpc/messages.js +56 -0
  162. package/dist/transport/grpc/messages.js.map +1 -0
  163. package/dist/transport/grpc/proto.d.ts +71 -0
  164. package/dist/transport/grpc/proto.d.ts.map +1 -0
  165. package/dist/transport/grpc/proto.js +67 -0
  166. package/dist/transport/grpc/proto.js.map +1 -0
  167. package/dist/transport/http.d.ts +62 -0
  168. package/dist/transport/http.d.ts.map +1 -0
  169. package/dist/transport/http.js +169 -0
  170. package/dist/transport/http.js.map +1 -0
  171. package/dist/transport/ndjson-row-source.d.ts +38 -0
  172. package/dist/transport/ndjson-row-source.d.ts.map +1 -0
  173. package/dist/transport/ndjson-row-source.js +197 -0
  174. package/dist/transport/ndjson-row-source.js.map +1 -0
  175. package/dist/transport/rest-decode.d.ts +33 -0
  176. package/dist/transport/rest-decode.d.ts.map +1 -0
  177. package/dist/transport/rest-decode.js +162 -0
  178. package/dist/transport/rest-decode.js.map +1 -0
  179. package/dist/transport/rest-prepared-cache.d.ts +50 -0
  180. package/dist/transport/rest-prepared-cache.d.ts.map +1 -0
  181. package/dist/transport/rest-prepared-cache.js +101 -0
  182. package/dist/transport/rest-prepared-cache.js.map +1 -0
  183. package/dist/transport/rest-transport.d.ts +88 -0
  184. package/dist/transport/rest-transport.d.ts.map +1 -0
  185. package/dist/transport/rest-transport.js +388 -0
  186. package/dist/transport/rest-transport.js.map +1 -0
  187. package/dist/transport/transport-pool.d.ts +40 -0
  188. package/dist/transport/transport-pool.d.ts.map +1 -0
  189. package/dist/transport/transport-pool.js +48 -0
  190. package/dist/transport/transport-pool.js.map +1 -0
  191. package/dist/transport/transport.d.ts +199 -0
  192. package/dist/transport/transport.d.ts.map +1 -0
  193. package/dist/transport/transport.js +11 -0
  194. package/dist/transport/transport.js.map +1 -0
  195. package/dist/values/decode.d.ts +39 -0
  196. package/dist/values/decode.d.ts.map +1 -0
  197. package/dist/values/decode.js +75 -0
  198. package/dist/values/decode.js.map +1 -0
  199. package/dist/values/encode.d.ts +45 -0
  200. package/dist/values/encode.d.ts.map +1 -0
  201. package/dist/values/encode.js +271 -0
  202. package/dist/values/encode.js.map +1 -0
  203. package/dist/values/ticks.d.ts +31 -0
  204. package/dist/values/ticks.d.ts.map +1 -0
  205. package/dist/values/ticks.js +52 -0
  206. package/dist/values/ticks.js.map +1 -0
  207. package/dist/values/typed.d.ts +67 -0
  208. package/dist/values/typed.d.ts.map +1 -0
  209. package/dist/values/typed.js +134 -0
  210. package/dist/values/typed.js.map +1 -0
  211. package/dist/values/uuid.d.ts +27 -0
  212. package/dist/values/uuid.d.ts.map +1 -0
  213. package/dist/values/uuid.js +76 -0
  214. package/dist/values/uuid.js.map +1 -0
  215. package/dist/vector.d.ts +26 -0
  216. package/dist/vector.d.ts.map +1 -0
  217. package/dist/vector.js +48 -0
  218. package/dist/vector.js.map +1 -0
  219. package/package.json +86 -0
  220. package/proto/camus_sql.proto +566 -0
@@ -0,0 +1,406 @@
1
+ /**
2
+ * This file is part of CamusDB
3
+ *
4
+ * For the full copyright and license information, please view the LICENSE.txt
5
+ * file that was distributed with this source code.
6
+ */
7
+ import { CamusBackupClient } from './backup.js';
8
+ import type { CamusCacheMetadata } from './cache.js';
9
+ import type { CamusClientOptions, CamusProtocol, ResolvedConfig } from './config.js';
10
+ import type { CamusTransactionOptions } from './options.js';
11
+ import { CamusQueryStream } from './query-stream.js';
12
+ import type { CamusColumn } from './result-set.js';
13
+ import type { CamusRoutingAdvice } from './routing/advice.js';
14
+ import { CamusTransaction } from './transaction.js';
15
+ import type { CamusBranchRow } from './transport/transport.js';
16
+ import type { Int64Mode } from './values/decode.js';
17
+ import type { Parameters } from './values/encode.js';
18
+ /** What one statement may override for itself. */
19
+ export interface StatementOptions {
20
+ /** The transaction to run inside. Without one the statement runs in its own short transaction. */
21
+ readonly transaction?: CamusTransaction | undefined;
22
+ /** Ends the statement early. */
23
+ readonly signal?: AbortSignal | undefined;
24
+ /** A deadline for this statement alone, in seconds. */
25
+ readonly timeoutSeconds?: number | undefined;
26
+ /** How an `int64` column reaches the caller, for this statement alone. */
27
+ readonly int64?: Int64Mode | undefined;
28
+ }
29
+ /** Options for a statement that begins its own short transaction. */
30
+ export interface AutocommitStatementOptions extends StatementOptions {
31
+ /** Concurrency knobs for the short transaction the server begins for this statement. */
32
+ readonly transactionOptions?: CamusTransactionOptions | undefined;
33
+ }
34
+ /** The rows of one query, and what the server reported about running it. */
35
+ export interface QueryResult<T> {
36
+ /** The rows, as plain objects keyed by column name. */
37
+ readonly rows: T[];
38
+ /** The output columns, in order. Present even when there are no rows. */
39
+ readonly columns: CamusColumn[];
40
+ readonly rowCount: number;
41
+ /** How a cache-hinted `SELECT` resolved, or `undefined` when the statement carried no hint. */
42
+ readonly cacheMetadata?: CamusCacheMetadata | undefined;
43
+ /**
44
+ * The routing advice the response carried. It arrives only on a client with routing on, and only
45
+ * for a statement the server judged eligible. It is diagnostic: the driver has already applied it.
46
+ */
47
+ readonly routingAdvice?: CamusRoutingAdvice | undefined;
48
+ }
49
+ /** What a write statement did. */
50
+ export interface ExecuteResult {
51
+ readonly affectedRows: number;
52
+ /** See `QueryResult.routingAdvice`. */
53
+ readonly routingAdvice?: CamusRoutingAdvice | undefined;
54
+ }
55
+ /** How `client.transaction` runs and retries a unit of work. */
56
+ export interface TransactionRunOptions {
57
+ /** How many times the work runs in total, the first attempt included. Default 5. */
58
+ readonly maxAttempts?: number | undefined;
59
+ /** Concurrency knobs for the transaction. */
60
+ readonly transactionOptions?: CamusTransactionOptions | undefined;
61
+ /** Ends the work early. */
62
+ readonly signal?: AbortSignal | undefined;
63
+ }
64
+ /**
65
+ * A connection to one CamusDB database.
66
+ *
67
+ * A client is cheap to create and safe to share. It holds no socket of its own: the endpoint
68
+ * rotation, the bearer token, the wire transport, and the learned routes are shared process-wide
69
+ * by what they actually depend on, so building a client per request costs almost nothing and still
70
+ * reuses the connections, the token, and the prepared statements a long-lived one would.
71
+ *
72
+ * ```ts
73
+ * const client = CamusClient.fromConnectionString('Endpoint=http://localhost:8082;Database=test');
74
+ *
75
+ * const { rows } = await client.query<Robot>('SELECT * FROM robots WHERE year = @year', { year: 1974 });
76
+ * ```
77
+ *
78
+ * Every method that reaches the server accepts an `AbortSignal` and a per-statement timeout.
79
+ */
80
+ export declare class CamusClient implements AsyncDisposable {
81
+ private readonly runtime;
82
+ private backupClient;
83
+ /**
84
+ * Builds a client from an options object, or from a connection string.
85
+ *
86
+ * ```ts
87
+ * new CamusClient({ endpoint: 'http://localhost:8082', database: 'test' });
88
+ * new CamusClient('Endpoint=http://localhost:8082;Database=test');
89
+ * ```
90
+ */
91
+ constructor(options: CamusClientOptions | string);
92
+ /**
93
+ * Builds a client from a `key=value;key=value` connection string.
94
+ *
95
+ * ```ts
96
+ * CamusClient.fromConnectionString('Endpoint=http://localhost:8082;Database=test;User=app;Password=secret');
97
+ * ```
98
+ *
99
+ * Keys are matched without regard to case. Wrap a value in quotes to keep a semicolon or
100
+ * surrounding spaces in it, and double the quote character to include one.
101
+ */
102
+ static fromConnectionString(connectionString: string): CamusClient;
103
+ /** @internal The resolved configuration, for tests and diagnostics. */
104
+ get config(): ResolvedConfig;
105
+ /** The database statements run against. */
106
+ get database(): string;
107
+ /** The wire protocol this client speaks. */
108
+ get protocol(): CamusProtocol;
109
+ /** The bearer token currently held, or `undefined`. Reading it never triggers a login. */
110
+ get accessToken(): string | undefined;
111
+ /**
112
+ * The node's online backup administration API.
113
+ *
114
+ * It is server-level and node-wide, not scoped to this client's database, and it needs a
115
+ * superuser token when authentication is on.
116
+ */
117
+ get backups(): CamusBackupClient;
118
+ /** How many statements this client currently keeps prepared on the server. */
119
+ get preparedStatementCount(): number;
120
+ /** How many destinations learned routing currently holds. Zero when routing is off. */
121
+ get learnedRouteCount(): number;
122
+ /** Points this client at another database. It sends nothing. */
123
+ changeDatabase(database: string): void;
124
+ /** The configuration as text, with every secret masked. Safe to log. */
125
+ toString(): string;
126
+ /**
127
+ * Runs a `SELECT` and reads every row.
128
+ *
129
+ * ```ts
130
+ * const { rows } = await client.query<Robot>(
131
+ * 'SELECT id, name, year FROM robots WHERE year > @year',
132
+ * { year: 1970 },
133
+ * );
134
+ * ```
135
+ *
136
+ * Give a type argument to describe the row shape. It is not checked against the server's schema —
137
+ * nothing on this side can check that — so it states what you expect, and the driver maps each
138
+ * column to the JavaScript value its declared type calls for.
139
+ *
140
+ * Use `queryStream` when the result may be large: this method holds every row in memory.
141
+ */
142
+ query<T = Record<string, unknown>>(sql: string, parameters?: Parameters, options?: StatementOptions): Promise<QueryResult<T>>;
143
+ /** Runs a `SELECT` and reads its first row, or `undefined` when it returned none. */
144
+ queryOne<T = Record<string, unknown>>(sql: string, parameters?: Parameters, options?: StatementOptions): Promise<T | undefined>;
145
+ /**
146
+ * Runs a `SELECT` and reads the first column of its first row, or `undefined`.
147
+ *
148
+ * ```ts
149
+ * const total = await client.scalar<number>('SELECT COUNT(*) FROM robots');
150
+ * ```
151
+ */
152
+ scalar<T = unknown>(sql: string, parameters?: Parameters, options?: StatementOptions): Promise<T | undefined>;
153
+ /**
154
+ * Runs a `SELECT` and reports its rows one at a time, so a large result never fully materializes
155
+ * on this side.
156
+ *
157
+ * ```ts
158
+ * await using stream = await client.queryStream<Robot>('SELECT * FROM robots');
159
+ *
160
+ * for await (const robot of stream) {
161
+ * process(robot);
162
+ * }
163
+ * ```
164
+ *
165
+ * It is genuinely incremental over REST. Over gRPC the data plane multiplexes results over
166
+ * shared streams that decode a whole result before returning, so this buffers and replays: the
167
+ * caller's code is the same, but the memory saving is not there.
168
+ *
169
+ * The streaming path gives up the transparent retry of a serializable conflict that `query` has;
170
+ * see `CamusQueryStream`.
171
+ */
172
+ queryStream<T = Record<string, unknown>>(sql: string, parameters?: Parameters, options?: StatementOptions): Promise<CamusQueryStream<T>>;
173
+ /**
174
+ * Runs an `INSERT`, `UPDATE`, or `DELETE` and reports how many rows it changed.
175
+ *
176
+ * ```ts
177
+ * const { affectedRows } = await client.execute(
178
+ * 'UPDATE robots SET year = @year WHERE id = @id',
179
+ * { year: 1984, id: robotId },
180
+ * );
181
+ * ```
182
+ *
183
+ * A DDL statement is accepted here too and is sent to the DDL route, where it reports zero rows.
184
+ */
185
+ execute(sql: string, parameters?: Parameters, options?: AutocommitStatementOptions): Promise<ExecuteResult>;
186
+ /**
187
+ * Runs a schema statement: `CREATE TABLE`, `ALTER TABLE`, `DROP INDEX`, a view definition, and
188
+ * so on.
189
+ *
190
+ * `TRUNCATE` is refused inside an explicit transaction. It commits a replicated schema entry that
191
+ * a rollback cannot undo, so the server refuses it rather than promise a rollback it cannot
192
+ * deliver, and the driver refuses it before the round trip.
193
+ */
194
+ executeDdl(sql: string, options?: AutocommitStatementOptions): Promise<boolean>;
195
+ /**
196
+ * Inserts one row through the server's typed row-level route, naming a table and a column-to-value
197
+ * map instead of composing SQL.
198
+ *
199
+ * ```ts
200
+ * await client.insert('robots', { id: CamusObjectId.generateAsString(), name: 'r1', year: 1974 });
201
+ * ```
202
+ *
203
+ * It performs exactly what `INSERT INTO` performs, and takes the same authorization, endpoint
204
+ * health, and error translation. Use it to avoid building statement text for a hot write path.
205
+ */
206
+ insert(table: string, values: Parameters, options?: StatementOptions): Promise<number>;
207
+ /** Reports whether the server answers. */
208
+ ping(options?: {
209
+ signal?: AbortSignal;
210
+ timeoutSeconds?: number;
211
+ }): Promise<boolean>;
212
+ /**
213
+ * Begins an explicit transaction.
214
+ *
215
+ * Prefer `transaction`, which commits, rolls back, and retries for you. Use this when the unit of
216
+ * work does not fit inside one function — a saga driven by external events, say.
217
+ *
218
+ * ```ts
219
+ * await using txn = await client.beginTransaction();
220
+ *
221
+ * await client.execute('UPDATE accounts SET balance = balance - 10 WHERE id = @id', { id: from }, { transaction: txn });
222
+ * await client.execute('UPDATE accounts SET balance = balance + 10 WHERE id = @id', { id: to }, { transaction: txn });
223
+ *
224
+ * await txn.commit();
225
+ * ```
226
+ *
227
+ * With `await using`, a transaction that is left without a commit is rolled back as the block
228
+ * unwinds.
229
+ */
230
+ beginTransaction(options?: CamusTransactionOptions, signal?: AbortSignal): Promise<CamusTransaction>;
231
+ /**
232
+ * Runs a unit of work inside a transaction, committing it when the work returns and rolling it
233
+ * back when the work throws.
234
+ *
235
+ * ```ts
236
+ * await client.transaction(async (txn) => {
237
+ * await client.execute('UPDATE accounts SET balance = balance - @amount WHERE id = @id',
238
+ * { amount, id: from }, { transaction: txn });
239
+ * await client.execute('UPDATE accounts SET balance = balance + @amount WHERE id = @id',
240
+ * { amount, id: to }, { transaction: txn });
241
+ * });
242
+ * ```
243
+ *
244
+ * A serializable conflict is retried: the whole function runs again on a fresh transaction, with
245
+ * an exponential back-off. So the function must be safe to run more than once — it must not send
246
+ * an email, charge a card, or mutate state outside the database on a path that could repeat.
247
+ *
248
+ * A commit that reports an unresolved outcome is **not** retried this way. That case is resolved
249
+ * inside `CamusTransaction`, by re-issuing the same commit on the same handle, because replaying
250
+ * the work could apply an already-durable commit twice.
251
+ */
252
+ transaction<T>(work: (transaction: CamusTransaction) => Promise<T>, options?: TransactionRunOptions): Promise<T>;
253
+ /**
254
+ * Registers a statement with the server, so this and every later execution of the same SQL sends
255
+ * only a handle and its parameter values.
256
+ *
257
+ * Calling it is optional. The driver prepares a statement on its own once it has seen the same
258
+ * SQL a few times; see the `maxAutoPrepare` and `autoPrepareMinUsages` settings. Call it to skip
259
+ * that warm-up for a statement you already know is hot.
260
+ *
261
+ * Registration is idempotent per endpoint, database, and SQL, so preparing twice costs nothing. A
262
+ * statement that cannot be prepared — schema, administration, or a server with no support for it
263
+ * — is remembered as such and keeps running inline. That is not an error, and this method does
264
+ * not report one for it.
265
+ */
266
+ prepare(sql: string, options?: StatementOptions): Promise<void>;
267
+ /** Whether a statement is currently kept prepared for this client's database. */
268
+ isPrepared(sql: string): boolean;
269
+ /**
270
+ * Authenticates as a user and caches the resulting bearer token for every later statement.
271
+ *
272
+ * It is only needed when the credentials are not already in the configuration, which
273
+ * authenticates on first use, or to switch identity. Prefer it over putting a password in a
274
+ * connection string when the password comes from a secret manager at run time.
275
+ *
276
+ * Against a server with authentication off this still performs a real login and will fail, so do
277
+ * not call it unconditionally.
278
+ *
279
+ * @returns the minted token. The driver already holds it; it is reported for a caller that wants
280
+ * to pass it to another process.
281
+ */
282
+ login(user: string, password: string, signal?: AbortSignal): Promise<string>;
283
+ /**
284
+ * Revokes this client's bearer token on the server.
285
+ *
286
+ * The configured credentials are kept, so a later statement authenticates again on its own: this
287
+ * ends a session, it does not switch authentication off. It does nothing when no token has been
288
+ * minted.
289
+ */
290
+ logout(signal?: AbortSignal): Promise<void>;
291
+ /**
292
+ * Creates a database.
293
+ *
294
+ * Concurrent creations can collide transiently while the server allocates the shared database id
295
+ * sequence, which is what several environments provisioning in parallel produce. That is reported
296
+ * as a retryable condition and is retried here.
297
+ *
298
+ * With `ifNotExists`, a creation that loses a registration race is treated as success. The caller
299
+ * asked for the database to exist, and it does.
300
+ */
301
+ createDatabase(database?: string, options?: {
302
+ ifNotExists?: boolean;
303
+ signal?: AbortSignal;
304
+ }): Promise<void>;
305
+ /** Drops a database and everything in it. */
306
+ dropDatabase(database?: string, options?: {
307
+ signal?: AbortSignal;
308
+ }): Promise<void>;
309
+ /**
310
+ * Creates a copy-on-write branch of a database. It is the same operation as
311
+ * `CREATE DATABASE branch BRANCH FROM source`.
312
+ */
313
+ createBranchDatabase(branchName: string, sourceDatabaseName: string, options?: {
314
+ ifNotExists?: boolean;
315
+ signal?: AbortSignal;
316
+ }): Promise<void>;
317
+ /**
318
+ * Every transitive descendant of a database, ordered by depth and then by name. A database with
319
+ * no descendants reports an empty list.
320
+ */
321
+ showBranches(database?: string, options?: {
322
+ signal?: AbortSignal;
323
+ }): Promise<CamusBranchRow[]>;
324
+ /**
325
+ * The ancestry chain of a database, from its nearest parent to the root. A root database reports
326
+ * an empty list.
327
+ */
328
+ showAncestors(database?: string, options?: {
329
+ signal?: AbortSignal;
330
+ }): Promise<CamusBranchRow[]>;
331
+ /** Drops every cached query result in one family, for the current database. */
332
+ evictCache(name: string, options?: StatementOptions): Promise<void>;
333
+ /** Drops every cached query result for the current database. It never touches another one's. */
334
+ evictAllCache(options?: StatementOptions): Promise<void>;
335
+ /**
336
+ * Releases what this client holds on its own, which today is nothing: the transport, the token,
337
+ * and the endpoint rotation are shared, and outlive any one client.
338
+ *
339
+ * Call `CamusTransportPool.closeAll` to release the shared gRPC channels when a process is
340
+ * shutting down.
341
+ */
342
+ close(): Promise<void>;
343
+ [Symbol.asyncDispose](): Promise<void>;
344
+ private executeNonQuery;
345
+ /**
346
+ * Resolves where one statement is sent, in strict order of precedence.
347
+ *
348
+ * An explicit transaction's pinned endpoint always wins: its operations must land in one
349
+ * server-side ordering chain, and advice may inform the next transaction but never relocates
350
+ * this one. Then a fresh learned route, when routing is on. Then the pool's ordinary rotation.
351
+ *
352
+ * It also reports the router and the route entry's revision, so the reply's advice can be applied
353
+ * conditionally: a late reply must never overwrite a route a faster reply already refreshed. A
354
+ * router of `undefined` means "do not negotiate", and a client with routing off then sends
355
+ * requests identical to a pre-routing driver's.
356
+ *
357
+ * A deferred transaction — routing on, no statement yet — is started here by its first statement,
358
+ * on that statement's learned endpoint when one is fresh and on rotation otherwise. Every later
359
+ * statement finds the pin already set.
360
+ */
361
+ private route;
362
+ private buildRequest;
363
+ /**
364
+ * Whether this execution should name a prepared statement instead of carrying its SQL,
365
+ * registering it first when this is the execution that tips it over the threshold.
366
+ *
367
+ * The registration is awaited rather than started in the background, because the whole point is
368
+ * that this execution and the ones after it are cheap. Firing it off and running inline anyway
369
+ * would leave a busy statement racing its own warm-up. It costs one extra round trip, once per
370
+ * statement per endpoint.
371
+ *
372
+ * The caller passes the endpoint it already resolved. A REST handle is node-local and the pool
373
+ * rotates, so registering against a freshly drawn endpoint would routinely prepare on one node
374
+ * and execute on another — correct, because the transport re-registers where it lands, but a
375
+ * wasted round trip every single time.
376
+ */
377
+ private shouldPrepare;
378
+ /**
379
+ * Registers a statement and records what happened, reporting whether it may now run prepared.
380
+ *
381
+ * A registration failure never reaches the caller: preparing is an optimization, and the
382
+ * statement runs inline exactly as it would have if the driver had not tried. What the failure
383
+ * does decide is whether to ask again. A refusal specific to this statement stops asking for that
384
+ * statement; anything that says the node has no prepared-statement support at all stops asking
385
+ * for every statement, because one round trip per distinct SQL to relearn that is worse than not
386
+ * trying.
387
+ */
388
+ private register;
389
+ /**
390
+ * Releases a statement the policy evicted, so the server stops holding a handle this client has
391
+ * stopped using.
392
+ *
393
+ * It is best effort and off the caller's path: it is bookkeeping, not part of the statement being
394
+ * run. It takes the endpoint the caller already resolved rather than drawing a new one, which
395
+ * would rotate the pool as a side effect of housekeeping.
396
+ */
397
+ private release;
398
+ /**
399
+ * The effective options for a transaction or an autocommit statement: the caller's explicit knobs
400
+ * win, then this client's defaults, then the server default for any knob still unset.
401
+ */
402
+ private resolveTransactionOptions;
403
+ private decodeOptions;
404
+ private withTransientRetry;
405
+ }
406
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}