okmodel 0.6.0 → 0.7.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 (157) hide show
  1. package/README.md +100 -1131
  2. package/dist/adapters/capabilities.d.ts +3 -0
  3. package/dist/adapters/failure.d.ts +13 -2
  4. package/dist/adapters/lazy-errors.d.ts +22 -0
  5. package/dist/adapters/pg/bunsql-extra.d.ts +54 -3
  6. package/dist/adapters/pg/bunsql.d.ts +14 -1
  7. package/dist/adapters/pg/cursor.d.ts +17 -0
  8. package/dist/adapters/pg/no-inflight-timeout.d.ts +11 -8
  9. package/dist/adapters/pg/nodepostgres-extra.d.ts +22 -1
  10. package/dist/adapters/pg/nodepostgres.d.ts +12 -0
  11. package/dist/adapters/pg/pglite-wire.d.ts +24 -0
  12. package/dist/adapters/pg/pglite.d.ts +10 -0
  13. package/dist/adapters/pg/postgres-extra.d.ts +27 -11
  14. package/dist/adapters/pg/reserved.d.ts +42 -0
  15. package/dist/adapters/pg/session.d.ts +0 -18
  16. package/dist/contracts/connection.d.ts +7 -6
  17. package/dist/dialects/pg/floor.d.ts +68 -0
  18. package/dist/dialects/pg/index.d.ts +6 -1
  19. package/dist/dialects/pg/index.js +49 -159
  20. package/dist/dialects/pg/keys.d.ts +11 -8
  21. package/dist/dialects/pg/model.d.ts +40 -0
  22. package/dist/dialects/pg/morph.d.ts +43 -0
  23. package/dist/dialects/pg/operator-fit.d.ts +2 -2
  24. package/dist/dialects/pg/operators.d.ts +14 -7
  25. package/dist/dialects/pg/ops/bucket.d.ts +65 -0
  26. package/dist/dialects/pg/ops/inc.d.ts +2 -2
  27. package/dist/dialects/pg/ops/matches.d.ts +9 -12
  28. package/dist/dialects/pg/ops/relevance.d.ts +13 -0
  29. package/dist/dialects/pg/ops/search-query.d.ts +22 -0
  30. package/dist/dialects/pg/ops/window.d.ts +103 -0
  31. package/dist/dialects/pg/preset.d.ts +1 -1
  32. package/dist/dialects/pg/relations.d.ts +100 -3
  33. package/dist/dialects/pg/schema.d.ts +31 -3
  34. package/dist/dialects/pg/view/index.js +1 -1
  35. package/dist/runtime/aggregate.d.ts +8 -2
  36. package/dist/runtime/bucket-group.d.ts +70 -0
  37. package/dist/runtime/conflict.d.ts +22 -4
  38. package/dist/runtime/include.d.ts +0 -8
  39. package/dist/runtime/inflight.d.ts +1 -1
  40. package/dist/runtime/page.d.ts +4 -1
  41. package/dist/runtime/pg/bun.js +12 -6
  42. package/dist/runtime/pg/pg.js +5 -5
  43. package/dist/runtime/pg/pglite.d.ts +1 -0
  44. package/dist/runtime/pg/pglite.js +9 -9
  45. package/dist/runtime/pg/postgresjs.js +5 -5
  46. package/dist/runtime/plan.d.ts +95 -5
  47. package/dist/runtime/read-stream.d.ts +13 -16
  48. package/dist/runtime/result-name.d.ts +17 -0
  49. package/dist/runtime/server-check.d.ts +3 -3
  50. package/dist/runtime/sort-bind.d.ts +21 -0
  51. package/dist/runtime/sort.d.ts +56 -0
  52. package/dist/runtime/sync.d.ts +70 -0
  53. package/dist/runtime/tenancy/index.js +7 -5
  54. package/dist/runtime/text-search.d.ts +20 -0
  55. package/dist/runtime/traits/index.d.ts +80 -0
  56. package/dist/runtime/traits/index.js +175 -11
  57. package/dist/runtime/tree.d.ts +38 -0
  58. package/dist/runtime/types.d.ts +218 -22
  59. package/dist/runtime/validate/index.js +2 -2
  60. package/dist/runtime/version.d.ts +39 -0
  61. package/dist/runtime/window.d.ts +21 -0
  62. package/dist/runtime/write.d.ts +54 -2
  63. package/dist/shared/{wkme6tep.js → 14vx95q4.js} +8 -16
  64. package/dist/shared/1est4ezg.js +313 -0
  65. package/dist/shared/{4az561fn.js → 1qa0qajz.js} +8 -23
  66. package/dist/shared/{2cg3wnxc.js → 1w508jbr.js} +593 -130
  67. package/dist/shared/2c13q96h.js +18 -0
  68. package/dist/shared/{b4v57v3x.js → 2d3xq4ps.js} +2 -2
  69. package/dist/shared/{1nw1f3vs.js → 2shdbn8q.js} +7 -7
  70. package/dist/shared/3v7t1yrv.js +208 -0
  71. package/dist/shared/{x3jc53kg.js → 5e3tf63j.js} +2 -2
  72. package/dist/shared/5fe3kbsh.js +10 -0
  73. package/dist/shared/5v3xf80k.js +37 -0
  74. package/dist/shared/{c58secgj.js → 63qtkrca.js} +38 -4
  75. package/dist/shared/{2z7wv5tj.js → 67txcrcw.js} +55 -34
  76. package/dist/shared/79dt02vc.js +12 -0
  77. package/dist/shared/{8x72s86k.js → 7k9grvf6.js} +10 -4
  78. package/dist/shared/7kms6fvj.js +20 -0
  79. package/dist/shared/7mnme5tn.js +8 -0
  80. package/dist/shared/7n7ddwt4.js +6 -0
  81. package/dist/shared/{5j36z8dn.js → 81ebdx9p.js} +39 -70
  82. package/dist/shared/{knmes2kh.js → 8skf0cam.js} +1 -1
  83. package/dist/shared/9a4ae4p8.js +31 -0
  84. package/dist/shared/9y3mmmh1.js +436 -0
  85. package/dist/shared/ab9gmbwy.js +213 -0
  86. package/dist/shared/{f0f1n281.js → ax7qv55k.js} +2 -2
  87. package/dist/shared/{g90m9b0g.js → aytqh5y2.js} +6 -5
  88. package/dist/shared/{vjpnzwjz.js → b5pftnn2.js} +1 -1
  89. package/dist/shared/{ag4c7516.js → b76b8d95.js} +2 -2
  90. package/dist/shared/{vmfkhszw.js → bg3rym3g.js} +33 -26
  91. package/dist/shared/{mb2ycs1p.js → bm22fvzr.js} +15 -15
  92. package/dist/shared/{q3j1tq7a.js → bz84tkzm.js} +148 -23
  93. package/dist/shared/{31vm914h.js → cm3w0ywp.js} +15 -16
  94. package/dist/shared/cn957f8d.js +179 -0
  95. package/dist/shared/{gwn6v667.js → cnkky55j.js} +25 -14
  96. package/dist/shared/{ys0xzyaj.js → dkxgzaqd.js} +224 -19
  97. package/dist/shared/dzj09cye.js +10 -0
  98. package/dist/shared/exn3sd90.js +359 -0
  99. package/dist/shared/g6evj1j3.js +66 -0
  100. package/dist/shared/ga9j92qj.js +25 -0
  101. package/dist/shared/{t3g0k88x.js → gs74dbj5.js} +16 -12
  102. package/dist/shared/gzaveazc.js +285 -0
  103. package/dist/shared/{2jd1sn0e.js → hyh73qk6.js} +1 -1
  104. package/dist/shared/{r1fdd0f6.js → je4axnm8.js} +5 -2
  105. package/dist/shared/{1f0xa3cb.js → jvd0mqag.js} +3 -3
  106. package/dist/shared/jznfax0y.js +155 -0
  107. package/dist/shared/{cgbamx3e.js → kb2sdhfb.js} +7 -4
  108. package/dist/shared/{wt5rzv1h.js → kr0jzbw2.js} +5 -5
  109. package/dist/shared/{p6bjzq9q.js → ktz42yez.js} +12 -4
  110. package/dist/shared/{p248q79y.js → m6p12kbr.js} +2 -2
  111. package/dist/shared/{r6nwkxnt.js → m7n9h2a5.js} +4 -4
  112. package/dist/shared/{672t5vym.js → mss6ctgv.js} +2 -2
  113. package/dist/shared/{929h19xp.js → mtaszv5a.js} +40 -10
  114. package/dist/shared/{b3awxn7h.js → n816peh1.js} +1 -1
  115. package/dist/shared/nbw1z4yd.js +18 -0
  116. package/dist/shared/{nx9hh281.js → p6qc5gcp.js} +12 -11
  117. package/dist/shared/{pjr6xrm5.js → pbp1ss85.js} +20 -17
  118. package/dist/shared/pt94kz7f.js +6 -0
  119. package/dist/shared/q5c6ngn3.js +13 -0
  120. package/dist/shared/{xq0mvhts.js → rs73fca9.js} +4 -4
  121. package/dist/shared/{r11n8grd.js → sfz1ksn6.js} +7 -4
  122. package/dist/shared/{wynzeggs.js → svncdeh5.js} +6 -6
  123. package/dist/shared/{j60w0dvr.js → tbrvgw6z.js} +57 -38
  124. package/dist/shared/te5as7z7.js +622 -0
  125. package/dist/shared/{ttmg09vd.js → tsvww22q.js} +1 -1
  126. package/dist/shared/{y2t3jktd.js → ttsqgp4p.js} +19 -12
  127. package/dist/shared/{x72jb7ad.js → v8g1vgv8.js} +1 -1
  128. package/dist/shared/{sbdme3vy.js → vb6qfyve.js} +60 -10
  129. package/dist/shared/{5d8t84hg.js → vczs8gd4.js} +14 -14
  130. package/dist/shared/{5yv4k6a6.js → vqrjpcqn.js} +144 -2
  131. package/dist/shared/{3fqwmr09.js → w72kgg4q.js} +4 -4
  132. package/dist/shared/{1z04fa85.js → w79hsckn.js} +12 -57
  133. package/dist/shared/{09p049xa.js → wa07eas9.js} +42 -14
  134. package/dist/shared/{32cnm7kn.js → x933k9a3.js} +74 -38
  135. package/dist/shared/{n076ydsc.js → xhfsfkgk.js} +62 -28
  136. package/dist/shared/xjk7hnn5.js +272 -0
  137. package/dist/shared/{hazqqecq.js → xnxsed62.js} +50 -21
  138. package/dist/shared/y6njgyda.js +249 -0
  139. package/dist/shared/{8etn7d8w.js → z7s6fpxv.js} +1 -1
  140. package/dist/shared/{n7mcc1gk.js → zchaghkf.js} +4 -3
  141. package/dist/shared/zm0ptry0.js +40 -0
  142. package/dist/shared/{nsva2a6b.js → znm0bpp5.js} +3 -0
  143. package/dist/shared/zp9fmend.js +145 -0
  144. package/dist/tooling/cli.js +11 -11
  145. package/dist/tooling/migrate/engine.d.ts +3 -2
  146. package/dist/tooling/migrate/index.js +7 -7
  147. package/dist/tooling/testing/index.js +1 -1
  148. package/package.json +4 -2
  149. package/dist/shared/3qnhc7w5.js +0 -38
  150. package/dist/shared/7m88x3e9.js +0 -45
  151. package/dist/shared/8dqhth8c.js +0 -12
  152. package/dist/shared/d5azex6s.js +0 -6
  153. package/dist/shared/j3rkk835.js +0 -99
  154. package/dist/shared/k68eedmy.js +0 -85
  155. package/dist/shared/venqrjna.js +0 -216
  156. package/dist/shared/wxr8cwns.js +0 -6
  157. package/dist/shared/zm0mafk4.js +0 -92
@@ -5,6 +5,9 @@
5
5
  * OKM11xx for a driver that lacks a flag: OKM1110 is the engine-version gate,
6
6
  * and OKM1801 is a dialect mismatch. This module does not invent a code and
7
7
  * does not throw for a missing flag.
8
+ *
9
+ * `stream` means the driver can open a server cursor. `.stream()` does not
10
+ * read it. That method walks keyset batches on every driver.
8
11
  */
9
12
  import type { DriverCapabilities } from "../contracts/driver.js";
10
13
  /** Capability names a caller can read. */
@@ -13,10 +13,21 @@ export declare function driverErrors(): Promise<ErrorModule>;
13
13
  /**
14
14
  * Rejects with a closed-pool {@link import("./error.js").DriverError}.
15
15
  *
16
- * @param message - Error text
16
+ * The text and SQLSTATE `08006` load with the lazy error module. Classification
17
+ * reads the SQLSTATE. The message is "The pool is closed."
18
+ *
19
+ * @returns A rejected promise
20
+ */
21
+ export declare function rejectClosed(): Promise<never>;
22
+ /**
23
+ * Rejects with OKM1120 when a driver cannot cancel a positive timeout.
24
+ *
25
+ * The message stays `timeout`. Kind stays `invalid`. Bun.sql and PGlite call
26
+ * this. Other drivers do not, so their connect graphs omit it.
27
+ *
17
28
  * @returns A rejected promise
18
29
  */
19
- export declare function rejectClosed(message?: string): Promise<never>;
30
+ export declare function rejectUncancellable(): Promise<never>;
20
31
  /**
21
32
  * Rejects with kind `cancelled`.
22
33
  *
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Error text a connect entry does not need until a call fails.
3
+ *
4
+ * Loaded on the first closed pool or on a positive `timeout` for a driver
5
+ * that cannot cancel. A successful execute does not import this module.
6
+ */
7
+ /**
8
+ * OKM1120 for a positive `timeout` on Bun.sql or PGlite.
9
+ *
10
+ * Kind stays `invalid`. The message stays `timeout` (D224, D239).
11
+ *
12
+ * @returns A rejected promise
13
+ */
14
+ export declare function refused(): Promise<never>;
15
+ /**
16
+ * A pool that has already been closed.
17
+ *
18
+ * The message is for people. Classification reads SQLSTATE `08006`.
19
+ *
20
+ * @returns A rejected promise
21
+ */
22
+ export declare function closed(): Promise<never>;
@@ -1,9 +1,11 @@
1
1
  /**
2
2
  * Reserved connections for Bun.sql.
3
3
  *
4
- * Loaded on the first reserve, batch, or stream. A read does not use it.
4
+ * Loaded on the first reserve, batch, stream, or dead connection. A read that
5
+ * succeeds does not use it.
5
6
  */
6
- import type { DriverConnection } from "../../contracts/driver.js";
7
+ import type { ReservedSQL, SQL } from "bun";
8
+ import type { DriverConnection, WireValue } from "../../contracts/driver.js";
7
9
  import { type HeldPool } from "./bunsql.js";
8
10
  /**
9
11
  * Checks out one connection and clears it on release.
@@ -14,4 +16,53 @@ import { type HeldPool } from "./bunsql.js";
14
16
  * @param held - The pool and its counters
15
17
  * @returns A connection the caller must release
16
18
  */
17
- export declare function checkout(held: HeldPool): Promise<DriverConnection>;
19
+ /**
20
+ * Drops a dead pooled socket, then runs `again` once when that is safe.
21
+ *
22
+ * A `57P01` or a socket Bun has already closed is evicted before another
23
+ * statement can take it. A client read is tried once more when `depth` is 0.
24
+ * A raw pool retries only when the socket had already closed, or Bun rejected
25
+ * the statement before the server saw it, so a query killed while it was
26
+ * running is not started again. `again` does not pass through `recover`.
27
+ *
28
+ * @param sql - The pool
29
+ * @param error - The failure from the first attempt
30
+ * @param text - Statement text, used to decide the retry
31
+ * @param depth - Open transaction depth. Above zero, an earlier command was sent
32
+ * @param clientRead - The pool was opened for a client, which retries a read once
33
+ * @param closedDuring - `onclose` ran after this statement was sent
34
+ * @param again - The same statement, on whatever connection the pool hands out next
35
+ * @returns The retried result, or a rejection of `error`
36
+ */
37
+ export declare function recover<T>(sql: SQL, error: unknown, text: string, depth: number, clientRead: boolean, closedDuring: boolean, again: () => Promise<T>): Promise<T>;
38
+ /**
39
+ * Spends a closed socket before the caller's statement is sent.
40
+ *
41
+ * @param sql - The pool
42
+ */
43
+ export declare function drainClosed(sql: SQL): Promise<void>;
44
+ /**
45
+ * Subscribes on one pooled connection.
46
+ *
47
+ * @param sql - The pool
48
+ * @param parked - Reserved handles to put back first
49
+ * @param closed - The pool is closed
50
+ * @param channel - Notify channel
51
+ * @param onNotify - Payload callback
52
+ * @returns Stops the subscription
53
+ */
54
+ export declare function listen(sql: SQL, parked: ReservedSQL[], closed: boolean, channel: string, onNotify: (payload: string) => void): Promise<() => Promise<void>>;
55
+ export declare function checkout(held: HeldPool): Promise<DriverConnection & {
56
+ evict(): void;
57
+ }>;
58
+ /**
59
+ * Yields cursor chunks from one checked-out Bun.sql connection.
60
+ *
61
+ * @param checkout - Reserves the connection
62
+ * @param text - Query to stream
63
+ * @param params - Wire parameters
64
+ * @returns Chunks of wire rows
65
+ */
66
+ export declare function streamRows(checkout: () => Promise<DriverConnection & {
67
+ evict?: () => void;
68
+ }>, text: string, params: readonly WireValue[] | undefined): AsyncIterable<readonly (readonly WireValue[])[]>;
@@ -11,9 +11,10 @@
11
11
  */
12
12
  import { SQL, type ReservedSQL } from "bun";
13
13
  import type { DriverPool, DriverPoolConfig, WireValue } from "../../contracts/driver.js";
14
+ import { DriverError } from "../error.js";
14
15
  import { noticeBuffer, type WireQuery } from "./session.js";
15
16
  export { BUNSQL_CAPABILITIES as capabilities, hasCapability, readCapability, } from "../capabilities.js";
16
- export { DriverError } from "../error.js";
17
+ export { DriverError };
17
18
  /** TLS values Bun.sql accepts that this adapter forwards. */
18
19
  export type BunSqlTls = boolean | "disable" | "allow" | "prefer" | "require" | "verify-ca" | "verify-full";
19
20
  /** Options for {@link open}. */
@@ -40,7 +41,19 @@ export type HeldPool = {
40
41
  readonly counters: Counters;
41
42
  readonly notices: ReturnType<typeof noticeBuffer>;
42
43
  readonly isClosed: () => boolean;
44
+ /** Sockets this pool has closed. The count never returns to zero. */
45
+ readonly closures: () => number;
43
46
  };
47
+ /**
48
+ * Marks a pool opened for a client.
49
+ *
50
+ * A client read that finds a dead socket is tried once. A pool from raw
51
+ * {@link open} is not marked, so a statement the server killed while it was
52
+ * running is not started again.
53
+ *
54
+ * @param pool - The pool `connect` just opened
55
+ */
56
+ export declare function markClientPool(pool: DriverPool): void;
44
57
  /** Pool occupancy. */
45
58
  export type Counters = {
46
59
  reserved: number;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Server-side cursor for drivers that stream through a checked-out connection.
3
+ *
4
+ * Loaded with the stream chunk. A read does not import this.
5
+ */
6
+ import type { ExecuteResult, WireValue } from "../../contracts/driver.js";
7
+ /**
8
+ * Yields cursor chunks from one connection that is already checked out.
9
+ *
10
+ * The cursor is session-local. `ROLLBACK` in the end drops it.
11
+ *
12
+ * @param run - Executes on the checked-out connection
13
+ * @param text - Query to stream
14
+ * @param params - Wire parameters
15
+ * @returns Chunks of wire rows
16
+ */
17
+ export declare function cursorStream(run: (text: string, params?: readonly WireValue[]) => Promise<ExecuteResult>, text: string, params: readonly WireValue[] | undefined): AsyncIterable<readonly (readonly WireValue[])[]>;
@@ -1,17 +1,20 @@
1
1
  /**
2
2
  * Refusal for a driver that cannot cancel an in-flight statement (D224).
3
3
  *
4
- * Bun.sql and PGlite throw OKM1120 for a positive `timeout`. The message
5
- * stays `timeout` because the PGlite connect graph has two gzip bytes left.
6
- * Kind is `invalid`, which separates it from kind `timeout`. `timeout: 0`
7
- * still fails immediately as kind `timeout`. `signal` is unchanged.
8
- * postgres.js and node-postgres do not import this.
4
+ * Bun.sql and PGlite refuse a positive `timeout`. The OKM1120 text loads with
5
+ * the lazy error module, so a connect entry does not carry it. Kind is
6
+ * `invalid`, which separates it from kind `timeout`. `timeout: 0` still fails
7
+ * immediately as kind `timeout`. `signal` is unchanged. postgres.js and
8
+ * node-postgres do not import this.
9
9
  */
10
10
  /**
11
- * Throws OKM1120 when `timeout` is a positive number.
11
+ * Returns a rejected OKM1120 when `timeout` is a positive number.
12
12
  *
13
- * @param options - Per-call options. Absent, and a non-positive timeout, pass through
13
+ * Absent, and a non-positive timeout, return `undefined` so the caller runs.
14
+ *
15
+ * @param options - Per-call options
16
+ * @returns A rejected promise, or `undefined` when the call may run
14
17
  */
15
18
  export declare function noTimeout(options: {
16
19
  readonly timeout?: number;
17
- } | undefined): void;
20
+ } | undefined): Promise<never> | undefined;
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * Loaded on the first reserve, batch, or stream. A read does not use it.
5
5
  */
6
- import type { DriverConnection } from "../../contracts/driver.js";
6
+ import type { DriverConnection, WireValue } from "../../contracts/driver.js";
7
7
  import { type HeldPool } from "./nodepostgres.js";
8
8
  /**
9
9
  * Checks out one client and clears it on release.
@@ -16,3 +16,24 @@ import { type HeldPool } from "./nodepostgres.js";
16
16
  * @returns A connection the caller must release
17
17
  */
18
18
  export declare function checkout(held: HeldPool): Promise<DriverConnection>;
19
+ /**
20
+ * Listens on one checked-out client.
21
+ *
22
+ * The client has no pool error listener. One is set here so a dropped socket
23
+ * is not an uncaught `error` event.
24
+ *
25
+ * @param held - The pool and its counters
26
+ * @param channel - Notification channel
27
+ * @param onNotify - Called with each payload
28
+ * @returns Stops the listener
29
+ */
30
+ export declare function listen(held: HeldPool, channel: string, onNotify: (payload: string) => void): Promise<() => Promise<void>>;
31
+ /**
32
+ * Yields cursor chunks from one checked-out client.
33
+ *
34
+ * @param checkout - Reserves the connection
35
+ * @param text - Query to stream
36
+ * @param params - Wire parameters
37
+ * @returns Chunks of wire rows
38
+ */
39
+ export declare function streamRows(checkout: () => Promise<DriverConnection>, text: string, params: readonly WireValue[] | undefined): AsyncIterable<readonly (readonly WireValue[])[]>;
@@ -44,6 +44,18 @@ export type Counters = {
44
44
  reservedBusy: number;
45
45
  waiting: number;
46
46
  };
47
+ /**
48
+ * Attaches the one error listener a pool or a checked-out client can use.
49
+ *
50
+ * node-postgres types list `connect` and `notification` only. An idle pool
51
+ * client and a `LISTEN` client both emit `error` with no listener, and that
52
+ * is an uncaught exception. The default handler ignores it. The pool has
53
+ * already removed an idle client.
54
+ *
55
+ * @param source - Pool or client
56
+ * @param handle - What to do with the error
57
+ */
58
+ export declare function armDriverError(source: object, handle?: () => void): void;
47
59
  /**
48
60
  * Opens a node-postgres pool for one endpoint.
49
61
  *
@@ -0,0 +1,24 @@
1
+ /**
2
+ * PGlite wire codecs, loaded from {@link import("./pglite.ts").open}.
3
+ *
4
+ * A JS number, bigint, or boolean is sent as wire text. An `08P01` from a
5
+ * bad parameter is a driver error. A lost connection stays `unavailable`.
6
+ */
7
+ declare const parsers: Record<number, (value: string) => string>;
8
+ declare const serializers: Record<number, (value: unknown) => string>;
9
+ /** Identity parsers. The dialect owns parsing. */
10
+ export { parsers };
11
+ /** Wire-text serializers. Number, bigint, and boolean are text. */
12
+ export { serializers };
13
+ /**
14
+ * Maps a PGlite failure.
15
+ *
16
+ * `08P01` means the parameter did not fit the protocol message. The
17
+ * replacement carries the message and neither a SQLSTATE nor a cause, so the
18
+ * kind is `driver`. Any other failure, including a closed connection, is
19
+ * mapped unchanged.
20
+ *
21
+ * @param error - Caught value
22
+ * @returns A normalised driver error
23
+ */
24
+ export declare function fail(error: unknown): Promise<unknown>;
@@ -19,3 +19,13 @@ export type PgliteConfig = DriverPoolConfig & {
19
19
  * @returns The pool
20
20
  */
21
21
  export declare function open(config?: PgliteConfig): Promise<DriverPool>;
22
+ /**
23
+ * A pool whose `close` marks this client only.
24
+ *
25
+ * The inner pool stays open. A later call fails as unavailable.
26
+ * The body stays this small: the PGlite incremental figure is 11,510, 500 under its gate.
27
+ *
28
+ * @param pool - The caller's pool
29
+ * @returns A pool the client owns
30
+ */
31
+ export declare function seal(pool: DriverPool): DriverPool;
@@ -4,9 +4,14 @@
4
4
  * Loaded on the first reserve, batch, describe, or stream.
5
5
  */
6
6
  import type { Sql } from "postgres";
7
- import type { DescribeResult, DriverConnection, ExecuteResult, WireValue } from "../../contracts/driver.js";
7
+ import type { DescribeResult, DriverConnection, ExecuteOptions, ExecuteResult, Statement, WireValue } from "../../contracts/driver.js";
8
8
  import { type Watch } from "./call.js";
9
9
  import { type Canceller, type Counters, type NoticeBuffer } from "./postgresjs.js";
10
+ type Lost = {
11
+ on: boolean;
12
+ /** Rejects the reset or drain that is using this reserved connection. */
13
+ stop: () => void;
14
+ };
10
15
  /** State `open` shares with a checkout. */
11
16
  export type HeldPool = {
12
17
  readonly sql: Sql;
@@ -23,7 +28,7 @@ export type HeldPool = {
23
28
  * @param pool - The open pool
24
29
  * @returns A connection the caller must release
25
30
  */
26
- export declare function checkout(pool: HeldPool): Promise<DriverConnection>;
31
+ export declare function checkout(pool: HeldPool, timeoutMs?: number): Promise<DriverConnection>;
27
32
  /**
28
33
  * Describes a statement.
29
34
  *
@@ -42,18 +47,30 @@ export declare function describe(sql: Sql, text: string, params?: readonly WireV
42
47
  * @returns Chunks of wire rows
43
48
  */
44
49
  export declare function stream(sql: Sql, text: string, params?: readonly WireValue[]): AsyncIterable<readonly (readonly WireValue[])[]>;
45
- type Lost = {
46
- on: boolean;
47
- };
48
50
  /**
49
- * Rejects later writes once postgres.js reports the reserved socket closed.
51
+ * Settles `run` when `ms` elapses, the reserved connection closes, or every
52
+ * slot in the pool has closed.
50
53
  *
51
- * The first statement installs `onclose`. The checkout guard then refuses
52
- * the next statement, savepoint, or COMMIT before `socket.write`.
54
+ * A positive `ms` rejects with `timeout` and does not use the pool close hook.
55
+ * `link` is the reserved connection's lost flag, or the pool client.
53
56
  *
54
- * @param sql - Reserved connection
55
- * @param lost - Set when that socket closes
57
+ * @param ms - Deadline in milliseconds. `0` waits for a close
58
+ * @param run - Driver operation
59
+ * @param link - Connection flag, or the pool client when the wait has no connection
60
+ * @returns The operation's value
61
+ */
62
+ export declare function deadline<T>(ms: number, run: () => Promise<T>, link?: Lost | Sql): Promise<T>;
63
+ /**
64
+ * Checks out one connection, runs one batch, and releases it.
65
+ *
66
+ * The call timeout covers acquiring the connection and clearing it on release.
67
+ *
68
+ * @param pool - The open pool
69
+ * @param statements - Statements in order
70
+ * @param options - Call timeout and signal
71
+ * @returns One result per statement
56
72
  */
73
+ export declare function runBatch(pool: HeldPool, statements: readonly Statement[], options: ExecuteOptions | undefined): Promise<readonly ExecuteResult[]>;
57
74
  /**
58
75
  * Sets `lost` when the reserved socket closes.
59
76
  *
@@ -64,7 +81,6 @@ type Lost = {
64
81
  * @param lost - Set when that socket closes
65
82
  */
66
83
  export declare function watchReserved(sql: Sql, lost: Lost): void;
67
- /** Refcount a checkout or a listener borrows from the pool. */
68
84
  type Gate = {
69
85
  enter(): void;
70
86
  leave(): void;
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Shared reset and lost-connection guard for a reserved connection.
3
+ *
4
+ * node-postgres, Bun.sql, and PGlite load this with the first reserve.
5
+ * postgres.js keeps its own copy: a second module in that adapter bundle
6
+ * crosses the incremental size gate.
7
+ */
8
+ /** Set when the reserved socket is gone. */
9
+ export type Lost = {
10
+ on: boolean;
11
+ };
12
+ /**
13
+ * Clears session state on a reserved connection.
14
+ *
15
+ * A failed reset rolls back and tries once more. The caller supplies `run`.
16
+ *
17
+ * @param depth - Open transaction depth. Above zero, roll back first
18
+ * @param run - Executes one statement on the reserved connection
19
+ */
20
+ export declare function resetSession(depth: number, run: (text: string) => Promise<unknown>): Promise<void>;
21
+ /**
22
+ * Clears a PGlite session the same way {@link resetSession} clears the others.
23
+ *
24
+ * Rollback goes through the session so its depth is cleared on failure too.
25
+ *
26
+ * @param session - The single PGlite connection
27
+ */
28
+ export declare function resetQueried(session: {
29
+ inTransaction(): boolean;
30
+ rollback(): Promise<void>;
31
+ query(text: string, params: undefined, watch: undefined): Promise<unknown>;
32
+ }): Promise<void>;
33
+ /**
34
+ * Refuses the next statement after the reserved connection is gone.
35
+ *
36
+ * The first lost-connection error sets the flag.
37
+ *
38
+ * @param lost - Set when the socket is gone
39
+ * @param run - The statement
40
+ * @returns The statement, or a closed-pool rejection
41
+ */
42
+ export declare function refuseWhenLost<T>(lost: Lost, run: () => Promise<T>): Promise<T>;
@@ -23,13 +23,6 @@ export type NoticeBuffer = {
23
23
  readonly code?: string | undefined;
24
24
  }): void;
25
25
  };
26
- /**
27
- * Quotes one identifier.
28
- *
29
- * @param name - Channel or cursor name
30
- * @returns A double-quoted identifier
31
- */
32
- export declare function quoteIdent(name: string): string;
33
26
  /**
34
27
  * An empty notice buffer the pool fills as the server sends notices.
35
28
  *
@@ -81,14 +74,3 @@ export declare class WireSession implements BatchSession {
81
74
  private watched;
82
75
  private finishWatched;
83
76
  }
84
- /**
85
- * Yields cursor chunks from one connection that is already checked out.
86
- *
87
- * The cursor is session-local. `ROLLBACK` in the end drops it.
88
- *
89
- * @param run - Executes on the checked-out connection
90
- * @param text - Query to stream
91
- * @param params - Wire parameters
92
- * @returns Chunks of wire rows
93
- */
94
- export declare function cursorStream(run: (text: string, params?: readonly WireValue[]) => Promise<ExecuteResult>, text: string, params: readonly WireValue[] | undefined): AsyncIterable<readonly (readonly WireValue[])[]>;
@@ -24,8 +24,10 @@ export declare function isConnectionErrno(code: string): boolean;
24
24
  /**
25
25
  * Reports whether `error` is a dropped or refused connection.
26
26
  *
27
- * Constraint failures are not connection failures. `23505` stays a unique
28
- * violation even when it is raised at commit.
27
+ * The decision is a driver `code` ({@link isConnectionErrno}, including
28
+ * `CONNECT_TIMEOUT`, or `ERR_POSTGRES_CONNECTION_CLOSED`) or a SQLSTATE in
29
+ * class `08` or `57P01`–`57P03`. A server SQLSTATE outside that set is never
30
+ * a lost connection. Message text is not read.
29
31
  *
30
32
  * @param error - Caught value
31
33
  * @returns `true` when no session remains
@@ -35,10 +37,9 @@ export declare function isConnectionFailure(error: unknown): boolean;
35
37
  * Reports whether the connection is gone after `error`, or the outcome of a
36
38
  * statement on it is unknown (`outcome_unknown`).
37
39
  *
38
- * It reads what {@link isConnectionFailure} reads, plus the messages node-postgres
39
- * ("Connection terminated unexpectedly") and Bun.sql (`ERR_POSTGRES_CONNECTION_CLOSED`)
40
- * give, and the error's `cause`. Nothing more should be sent to such a connection:
41
- * not a rollback, not a reset. Loaded with the code that reserves a connection.
40
+ * It reads what {@link isConnectionFailure} reads, and the error's `cause`.
41
+ * Nothing more should be sent to such a connection: not a rollback, not a
42
+ * reset. Loaded with the code that reserves a connection.
42
43
  *
43
44
  * @param error - Caught value
44
45
  * @returns `true` when the session cannot be used again
@@ -0,0 +1,68 @@
1
+ /**
2
+ * Postgres majors a schema may name, and the features that read them.
3
+ *
4
+ * 15–18 are the majors okmodel runs. A major outside that range is refused
5
+ * when `schema()` runs. Messages read these numbers. They do not repeat them.
6
+ */
7
+ /** Majors `minPostgres` and `requires.postgres` accept, oldest first. */
8
+ export declare const POSTGRES_MAJORS: readonly [15, 16, 17, 18];
9
+ /** A major {@link POSTGRES_MAJORS} allows. */
10
+ export type PostgresMajor = (typeof POSTGRES_MAJORS)[number];
11
+ /**
12
+ * Oldest major connect accepts when the schema names no floor.
13
+ *
14
+ * A server below this is OKM1803.
15
+ */
16
+ export declare const POSTGRES_FLOOR = 15;
17
+ /**
18
+ * `uuidv7()` database default.
19
+ *
20
+ * Add the next feature constant beside this one, and name it on the minPostgres page.
21
+ */
22
+ export declare const UUIDV7_POSTGRES = 18;
23
+ /**
24
+ * Accepts a major from {@link POSTGRES_MAJORS}.
25
+ *
26
+ * @param value - Candidate from schema input
27
+ * @returns Whether `value` is 15, 16, 17, or 18
28
+ */
29
+ export declare function isPostgresMajor(value: unknown): value is PostgresMajor;
30
+ /**
31
+ * Reads a stored `>=N` floor.
32
+ *
33
+ * `readFloor`, `refuseUuidV7`, and `acceptServer` share this parse.
34
+ *
35
+ * @param postgres - Stored or input range
36
+ * @returns The major, or `NaN` when the text is not `>=` plus digits
37
+ */
38
+ export declare function parsePostgresFloor(postgres: string | undefined): number;
39
+ /**
40
+ * Stores a major as `>=N`.
41
+ *
42
+ * @param major - Allowed major
43
+ * @returns The stored floor text
44
+ */
45
+ export declare function formatPostgresFloor(major: number): string;
46
+ /**
47
+ * Definition error for a floor outside 15–18.
48
+ *
49
+ * @returns OKM1060 message
50
+ */
51
+ export declare function minPostgresDefinition(): string;
52
+ /**
53
+ * Sentence for a `uuidv7()` default the declared floor does not allow.
54
+ *
55
+ * @returns The OKM1812 message
56
+ */
57
+ export declare function uuidv7NeedsPostgres(): string;
58
+ /**
59
+ * Connect refusal when the server is below the schema floor.
60
+ *
61
+ * OKM1802 and OKM1803 share this sentence. OKM1803 passes {@link POSTGRES_FLOOR}.
62
+ * Loaded with the connect check, not with `schema()`.
63
+ *
64
+ * @param server - Major the server reported
65
+ * @param need - Major the schema requires
66
+ * @returns The message
67
+ */
68
+ export declare function serverNeedsPostgres(server: number, need: number): string;
@@ -4,6 +4,7 @@
4
4
  * Column types, codecs, picklists, `table()`, and `schema()`.
5
5
  * Each builder is a separate export so a bundle can keep only the ones it calls.
6
6
  */
7
+ export { type PostgresMajor } from "./floor.js";
7
8
  export { schema, type BuiltSchema, type SchemaCodecs, type SchemaInput, type SchemaRequires, } from "./schema.js";
8
9
  export { withOwner, type DeclaredOwner } from "./owner.js";
9
10
  export { index, sql, table, type AnyTable, type ColumnHandle, type IndexCall, type SqlText, type SqlValue, type FilterOperator, type Table, type TableOptions, } from "./table.js";
@@ -27,6 +28,8 @@ export { domain, enumColumn as enum } from "./enum.js";
27
28
  export { t } from "./namespace.js";
28
29
  export * as arr from "./ops/arr-ns.js";
29
30
  export * as json from "./ops/json-ns.js";
31
+ export { bucket, type Bucket, type BucketUnit, type WeekStart } from "./ops/bucket.js";
32
+ export { denseRank, rank, rowNumber, runningTotal, type Window, type WindowOrder, } from "./ops/window.js";
30
33
  export { between } from "./ops/between.js";
31
34
  export { containedBy } from "./ops/containedBy.js";
32
35
  export { contains } from "./ops/contains.js";
@@ -43,6 +46,8 @@ export { ilike } from "./ops/ilike.js";
43
46
  export { inList } from "./ops/inList.js";
44
47
  export { like } from "./ops/like.js";
45
48
  export { matches } from "./ops/matches.js";
49
+ export { relevance } from "./ops/relevance.js";
50
+ export type { SearchMatch } from "./operators.js";
46
51
  export { lt } from "./ops/lt.js";
47
52
  export { lte } from "./ops/lte.js";
48
53
  export { none } from "./ops/none.js";
@@ -52,4 +57,4 @@ export { or } from "./ops/or.js";
52
57
  export { overlaps } from "./ops/overlaps.js";
53
58
  export { path } from "./ops/path.js";
54
59
  export { startsWith } from "./ops/startsWith.js";
55
- export { many, manyThrough, one, type ManyRelation, type ManyThroughRelation, type OneRelation, type RelationCall, } from "./relations.js";
60
+ export { many, manyThrough, morph, morphMany, morphTo, one, type ManyRelation, type ManyThroughRelation, type MorphManyRelation, type MorphRelation, type OneRelation, type RelationCall, } from "./relations.js";