okmodel 0.1.1 → 0.2.1

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 (181) hide show
  1. package/README.md +32 -16
  2. package/dist/adapters/capabilities.d.ts +34 -0
  3. package/dist/adapters/pg/bunsql-extra.d.ts +17 -0
  4. package/dist/adapters/pg/bunsql.d.ts +60 -0
  5. package/dist/adapters/pg/call.d.ts +2 -12
  6. package/dist/adapters/pg/nodepostgres-extra.d.ts +18 -0
  7. package/dist/adapters/pg/nodepostgres.d.ts +57 -0
  8. package/dist/adapters/pg/postgres-extra.d.ts +50 -1
  9. package/dist/adapters/pg/postgresjs.d.ts +0 -4
  10. package/dist/adapters/pg/session.d.ts +94 -0
  11. package/dist/adapters/pg/watch.d.ts +18 -0
  12. package/dist/contracts/catalog/object.d.ts +1 -0
  13. package/dist/contracts/catalog/types.d.ts +15 -8
  14. package/dist/contracts/connection.d.ts +13 -0
  15. package/dist/contracts/driver.d.ts +18 -5
  16. package/dist/contracts/error.d.ts +17 -1
  17. package/dist/contracts/generator.d.ts +63 -0
  18. package/dist/contracts/index.d.ts +2 -2
  19. package/dist/contracts/index.js +1 -1
  20. package/dist/contracts/internal.js +11 -9
  21. package/dist/contracts/location.d.ts +24 -0
  22. package/dist/contracts/rows.d.ts +15 -0
  23. package/dist/dialects/pg/archive-bind.d.ts +22 -0
  24. package/dist/dialects/pg/column.d.ts +126 -9
  25. package/dist/dialects/pg/compile.d.ts +1 -0
  26. package/dist/dialects/pg/custom.d.ts +6 -0
  27. package/dist/dialects/pg/filter-parse.d.ts +19 -0
  28. package/dist/dialects/pg/filters.d.ts +19 -0
  29. package/dist/dialects/pg/index.d.ts +11 -2
  30. package/dist/dialects/pg/index.js +159 -1063
  31. package/dist/dialects/pg/keys.d.ts +19 -3
  32. package/dist/dialects/pg/model.d.ts +223 -2
  33. package/dist/dialects/pg/operator-fit.d.ts +86 -0
  34. package/dist/dialects/pg/operators.d.ts +39 -1
  35. package/dist/dialects/pg/ops/arr-append.d.ts +9 -0
  36. package/dist/dialects/pg/ops/arr-ns.d.ts +7 -0
  37. package/dist/dialects/pg/ops/arr-remove.d.ts +9 -0
  38. package/dist/dialects/pg/ops/containedBy.d.ts +9 -0
  39. package/dist/dialects/pg/ops/contains.d.ts +8 -4
  40. package/dist/dialects/pg/ops/hasAnyKey.d.ts +8 -0
  41. package/dist/dialects/pg/ops/hasKey.d.ts +8 -0
  42. package/dist/dialects/pg/ops/json-ns.d.ts +6 -0
  43. package/dist/dialects/pg/ops/json-set.d.ts +12 -0
  44. package/dist/dialects/pg/ops/matches.d.ts +16 -0
  45. package/dist/dialects/pg/ops/overlaps.d.ts +9 -0
  46. package/dist/dialects/pg/ops/path.d.ts +13 -0
  47. package/dist/dialects/pg/preset.d.ts +76 -0
  48. package/dist/dialects/pg/relations.d.ts +59 -2
  49. package/dist/dialects/pg/schema.d.ts +109 -5
  50. package/dist/dialects/pg/table.d.ts +130 -11
  51. package/dist/dialects/pg/temporal.d.ts +9 -7
  52. package/dist/dialects/pg/tenancy.d.ts +94 -0
  53. package/dist/dialects/pg/through.d.ts +21 -0
  54. package/dist/dialects/pg/trait.d.ts +141 -0
  55. package/dist/dialects/pg/where.d.ts +37 -0
  56. package/dist/runtime/aggregate.d.ts +25 -0
  57. package/dist/runtime/archive-handle.d.ts +18 -0
  58. package/dist/runtime/archive-rules.d.ts +12 -0
  59. package/dist/runtime/archive.d.ts +73 -0
  60. package/dist/runtime/batch.d.ts +20 -0
  61. package/dist/runtime/client.d.ts +114 -5
  62. package/dist/runtime/conflict.d.ts +2 -1
  63. package/dist/runtime/exposure.d.ts +27 -0
  64. package/dist/runtime/hookm.d.ts +39 -0
  65. package/dist/runtime/ids/index.d.ts +11 -0
  66. package/dist/runtime/ids/index.js +193 -0
  67. package/dist/runtime/ids/okid-extended.d.ts +19 -0
  68. package/dist/runtime/ids/okid-generator.d.ts +21 -0
  69. package/dist/runtime/ids/okid-shared.d.ts +89 -0
  70. package/dist/runtime/ids/okid.d.ts +24 -0
  71. package/dist/runtime/ids/uuid.d.ts +21 -0
  72. package/dist/runtime/lock.d.ts +22 -0
  73. package/dist/runtime/operator-sql.d.ts +8 -0
  74. package/dist/runtime/page.d.ts +25 -0
  75. package/dist/runtime/pg/bun.d.ts +30 -0
  76. package/dist/runtime/pg/bun.js +52 -0
  77. package/dist/runtime/pg/pg.d.ts +29 -0
  78. package/dist/runtime/pg/pg.js +52 -0
  79. package/dist/runtime/pg/pglite.js +16 -17
  80. package/dist/runtime/pg/postgresjs.js +14 -24
  81. package/dist/runtime/plan.d.ts +146 -7
  82. package/dist/runtime/preset-stack.d.ts +17 -0
  83. package/dist/runtime/presets.d.ts +48 -0
  84. package/dist/runtime/read-stream.d.ts +26 -0
  85. package/dist/runtime/safety/index.d.ts +159 -0
  86. package/dist/runtime/safety/index.js +294 -0
  87. package/dist/runtime/safety-hook.d.ts +42 -0
  88. package/dist/runtime/server-check.d.ts +34 -0
  89. package/dist/runtime/tenancy/index.d.ts +37 -0
  90. package/dist/runtime/tenancy/index.js +365 -0
  91. package/dist/runtime/trait-read.d.ts +30 -0
  92. package/dist/runtime/traits/index.d.ts +128 -0
  93. package/dist/runtime/traits/index.js +509 -0
  94. package/dist/runtime/transaction.d.ts +19 -0
  95. package/dist/runtime/tx.d.ts +22 -7
  96. package/dist/runtime/types.d.ts +376 -27
  97. package/dist/runtime/validate/bind.d.ts +11 -0
  98. package/dist/runtime/validate/closed.d.ts +16 -0
  99. package/dist/runtime/validate/engine.d.ts +41 -0
  100. package/dist/runtime/validate/hook.d.ts +17 -0
  101. package/dist/runtime/validate/index.d.ts +21 -0
  102. package/dist/runtime/validate/index.js +175 -0
  103. package/dist/runtime/validate/load.d.ts +13 -0
  104. package/dist/runtime/validate/places.d.ts +41 -0
  105. package/dist/runtime/validate/rules.d.ts +108 -0
  106. package/dist/runtime/validate/surface.d.ts +102 -0
  107. package/dist/runtime/write.d.ts +30 -5
  108. package/dist/shared/{fgqgsb5z.js → 0qkxbm1f.js} +2 -2
  109. package/dist/shared/0v1g424p.js +26 -0
  110. package/dist/shared/10tjenmd.js +210 -0
  111. package/dist/shared/{xqbhg6cn.js → 1dp5knt7.js} +95 -10
  112. package/dist/shared/38crxbgn.js +229 -0
  113. package/dist/shared/3a5ne750.js +158 -0
  114. package/dist/shared/4b9da9d7.js +138 -0
  115. package/dist/shared/4e4c6vq2.js +62 -0
  116. package/dist/shared/{x5x59srr.js → 4jzzghr6.js} +416 -83
  117. package/dist/shared/{ycwz42az.js → 52szzakm.js} +6 -26
  118. package/dist/shared/{05w44d8g.js → 5z4q2zda.js} +567 -18
  119. package/dist/shared/672t5vym.js +12 -0
  120. package/dist/shared/7m88x3e9.js +45 -0
  121. package/dist/shared/7mht49yd.js +1091 -0
  122. package/dist/shared/{mtkwv8wx.js → 7p2wbz7f.js} +1 -1
  123. package/dist/shared/83eaefwr.js +10 -0
  124. package/dist/shared/96ps4g1z.js +32 -0
  125. package/dist/shared/97g2jnrw.js +76 -0
  126. package/dist/shared/{xy79j5hq.js → 9k6vetvf.js} +25 -36
  127. package/dist/shared/{w8samvk1.js → a1gdp7j9.js} +1 -1
  128. package/dist/shared/a5sxz52y.js +13 -0
  129. package/dist/shared/{dynq16vb.js → b066g80h.js} +8 -6
  130. package/dist/shared/cstgkzdx.js +154 -0
  131. package/dist/shared/{523ft3e8.js → d04j53v8.js} +6 -5
  132. package/dist/shared/{y9m15dfv.js → d2whjz4k.js} +15 -9
  133. package/dist/shared/dd4f8mnx.js +307 -0
  134. package/dist/shared/e6wg00wd.js +164 -0
  135. package/dist/shared/e7a268fy.js +195 -0
  136. package/dist/shared/{kprcwaha.js → eaxwrgby.js} +4 -3
  137. package/dist/shared/{dkn3y60a.js → ecdzej21.js} +76 -112
  138. package/dist/shared/{hadrfb9h.js → edwqqryd.js} +17 -14
  139. package/dist/shared/{m3ypagh5.js → eqmtn1bj.js} +57 -5
  140. package/dist/shared/g1b5zzj9.js +75 -0
  141. package/dist/shared/g9f0zqce.js +376 -0
  142. package/dist/shared/ge03bfca.js +64 -0
  143. package/dist/shared/{yd1kzwn2.js → jns2wx4t.js} +55 -12
  144. package/dist/shared/k3ted12y.js +33 -0
  145. package/dist/shared/k7dwkhvq.js +31 -0
  146. package/dist/shared/{hd293j9g.js → kyxb62mc.js} +14 -2
  147. package/dist/shared/m9tv7xn7.js +404 -0
  148. package/dist/shared/mrq77sgw.js +55 -0
  149. package/dist/shared/mxmcdsh5.js +450 -0
  150. package/dist/shared/n442h54c.js +14 -0
  151. package/dist/shared/n47rd821.js +442 -0
  152. package/dist/shared/n4jqhpqz.js +27 -0
  153. package/dist/shared/{mkjmqjv4.js → nfzc5z0w.js} +2 -104
  154. package/dist/shared/nsva2a6b.js +42 -0
  155. package/dist/shared/ps43134h.js +69 -0
  156. package/dist/shared/{8b04d28c.js → py3nh7jy.js} +2 -2
  157. package/dist/shared/qa5dsc7z.js +86 -0
  158. package/dist/shared/{g5fhqmwe.js → qxa0yb9j.js} +6 -4
  159. package/dist/shared/r6nwkxnt.js +86 -0
  160. package/dist/shared/{jjb7yht9.js → rtnaqre0.js} +3 -3
  161. package/dist/shared/rwmrejjz.js +26 -0
  162. package/dist/shared/{zhc5vmgf.js → s6gqfn5j.js} +2 -2
  163. package/dist/shared/sacqha1y.js +70 -0
  164. package/dist/shared/{qk3hxfja.js → sfh4pk75.js} +5 -5
  165. package/dist/shared/{j5cn2963.js → t4tbsy9h.js} +13 -64
  166. package/dist/shared/{ngk8gj61.js → tbszx8mz.js} +15 -1
  167. package/dist/shared/v18jva5b.js +90 -0
  168. package/dist/shared/x9v1qgeb.js +201 -0
  169. package/dist/shared/xatfg0gn.js +193 -0
  170. package/dist/shared/xkz8g6by.js +225 -0
  171. package/dist/shared/{rgs0st28.js → xrfnq5k8.js} +237 -434
  172. package/dist/shared/ytg3xf9p.js +149 -0
  173. package/dist/shared/yw5c610b.js +48 -0
  174. package/dist/shared/zd93g3rq.js +31 -0
  175. package/dist/shared/zt8y0wzb.js +132 -0
  176. package/dist/shared/{p0cbr3g2.js → zwmqxb0g.js} +1 -1
  177. package/dist/tooling/cli.js +14 -10
  178. package/dist/tooling/migrate/commands.d.ts +10 -0
  179. package/dist/tooling/migrate/engine.d.ts +36 -0
  180. package/package.json +41 -4
  181. package/dist/shared/gk7cs7sp.js +0 -566
@@ -0,0 +1,63 @@
1
+ /**
2
+ * Client generators.
3
+ *
4
+ * A generator fills a column on insert. It is not a database default, so it
5
+ * stays off the catalog and its hash. Built-ins are marked by name so
6
+ * `connect({ generators })` can replace them.
7
+ */
8
+ /** Property that marks a function as a client generator. */
9
+ export declare const CLIENT_DEFAULT: unique symbol;
10
+ /** Built-in generator names, plus a caller-supplied function. */
11
+ export type GeneratorName = "uuidv4" | "uuidv7" | "okid" | "function";
12
+ /** Scalar options stored with a named generator. OKID uses these. */
13
+ export type GeneratorOptions = Readonly<Record<string, string | number | boolean>>;
14
+ /**
15
+ * What insert calls when a column was omitted.
16
+ *
17
+ * `label` is the catalog-output word for a client default. The catalog
18
+ * document itself does not store it.
19
+ */
20
+ export type ClientFill = {
21
+ readonly label: "client";
22
+ readonly name: GeneratorName;
23
+ readonly options?: GeneratorOptions;
24
+ readonly call: () => unknown;
25
+ };
26
+ /** A function `.default()` and `schema({ defaults: { id } })` accept. */
27
+ export type ClientGenerator<T = string> = (() => T) & {
28
+ readonly [CLIENT_DEFAULT]: {
29
+ readonly label: "client";
30
+ readonly name: Exclude<GeneratorName, "function">;
31
+ readonly options?: GeneratorOptions;
32
+ };
33
+ };
34
+ /**
35
+ * Replacements for the built-in generators, keyed by name.
36
+ *
37
+ * A test passes fixed functions here. A custom function with no name is left
38
+ * alone.
39
+ */
40
+ export type IdGenerators = {
41
+ readonly uuidv4?: () => string;
42
+ readonly uuidv7?: () => string;
43
+ readonly okid?: () => string;
44
+ };
45
+ /**
46
+ * Marks `call` as a named client generator.
47
+ *
48
+ * @typeParam T - Value the generator returns
49
+ * @param call - Function that produces one value
50
+ * @param name - Built-in name `connect({ generators })` can replace
51
+ * @param options - Scalar options stored beside the name
52
+ * @returns The same function, marked
53
+ */
54
+ export declare function clientGenerator<T>(call: () => T, name: Exclude<GeneratorName, "function">, options?: GeneratorOptions): ClientGenerator<T>;
55
+ /**
56
+ * Reads a client generator from a `.default()` argument.
57
+ *
58
+ * A marked built-in keeps its name. Any other function is a custom generator.
59
+ *
60
+ * @param value - Argument passed to `.default()` or `defaults.id`
61
+ * @returns The fill insert should call, or `undefined` when `value` is a literal
62
+ */
63
+ export declare function readClientGenerator(value: unknown): ClientFill | undefined;
@@ -6,6 +6,6 @@
6
6
  * live on `okmodel/internal`, so `table` and `index` on this entry are not a
7
7
  * second schema API.
8
8
  */
9
- export { CATALOG_CODES, COLUMN_CODES, ERROR_CATEGORIES, ERROR_KINDS, OkmError, safe, type CatalogCode, type ColumnCode, type QueryCode, type ErrorCategory, type ErrorColumns, type ErrorFields, type ErrorFix, type ErrorKind, type ErrorLog, type ErrorStatuses, type HttpError, type HttpErrorBody, type OkmErrorOptions, type SafeResult, } from "./error.js";
10
- export type { AnySchema, AnyTableShape, Insert, Register, Row, SchemaOf, TableName, Update, } from "./rows.js";
9
+ export { CATALOG_CODES, COLUMN_CODES, ERROR_CATEGORIES, ERROR_KINDS, OkmError, safe, type CatalogCode, type ColumnCode, type QueryCode, type ErrorCategory, type ErrorColumns, type ErrorFields, type ErrorFix, type ErrorKind, type ErrorLog, type ErrorStatuses, type HttpError, type HttpErrorBody, type OkmErrorOptions, type SafeResult, type ValidationIssue, } from "./error.js";
10
+ export type { AnySchema, AnyTableShape, Input, Insert, Register, Row, SchemaOf, TableName, Update, } from "./rows.js";
11
11
  export type { DescribeResult, DriverCapabilities, DriverConnection, DriverErrorFields, DriverFailureKind, DriverPool, DriverPoolConfig, DriverStats, ExecuteOptions, ExecuteResult, Notice, PreparedMode, Statement, TransactionMode, WireValue, } from "./driver.js";
@@ -5,7 +5,7 @@ import {
5
5
  ERROR_CATEGORIES2,
6
6
  OkmError2,
7
7
  safe2
8
- } from "../shared/ycwz42az.js";
8
+ } from "../shared/52szzakm.js";
9
9
  export {
10
10
  CATALOG_CODES2 as CATALOG_CODES,
11
11
  COLUMN_CODES2 as COLUMN_CODES,
@@ -1,10 +1,4 @@
1
1
  import {
2
- OWNERS2,
3
- OBJECT_KINDS2,
4
- BUILT_KINDS2,
5
- OBJECT_OPERATIONS2,
6
- KIND_OPERATIONS2,
7
- CATALOG_VERSION2,
8
2
  staticNamespace2,
9
3
  templateNamespace2,
10
4
  assertNamespace2,
@@ -19,7 +13,15 @@ import {
19
13
  index3,
20
14
  constraint2,
21
15
  sequence2
22
- } from "../shared/j5cn2963.js";
16
+ } from "../shared/t4tbsy9h.js";
17
+ import {
18
+ OWNERS2,
19
+ OBJECT_KINDS2,
20
+ BUILT_KINDS2,
21
+ OBJECT_OPERATIONS2,
22
+ KIND_OPERATIONS2,
23
+ CATALOG_VERSION2
24
+ } from "../shared/4e4c6vq2.js";
23
25
  import {
24
26
  utf8ByteLength2,
25
27
  sha2562,
@@ -28,12 +30,12 @@ import {
28
30
  assertIdentifier2,
29
31
  fitIdentifier2,
30
32
  deterministicName2
31
- } from "../shared/mkjmqjv4.js";
33
+ } from "../shared/nfzc5z0w.js";
32
34
  import {
33
35
  nearestName2,
34
36
  catalogError2,
35
37
  throwNamed2
36
- } from "../shared/ycwz42az.js";
38
+ } from "../shared/52szzakm.js";
37
39
  export {
38
40
  BUILT_KINDS2 as BUILT_KINDS,
39
41
  CATALOG_VERSION2 as CATALOG_VERSION,
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Authoring location for provenance.
3
+ *
4
+ * `source` is recorded when a table or a rule is defined. The catalog hash
5
+ * does not include it.
6
+ */
7
+ /**
8
+ * File and line of the caller `skip` frames above this function.
9
+ *
10
+ * Frames in this file are ignored. `skip` 1 is the direct caller, so a
11
+ * `table()` call records the schema line, not `table` itself.
12
+ *
13
+ * @param skip - Callers to pass before the frame that is recorded
14
+ * @returns `file.ts:line`, or `undefined` when the runtime has no stack
15
+ */
16
+ export declare function callerLocation(skip: number): string | undefined;
17
+ /**
18
+ * Appends a source location to an error message.
19
+ *
20
+ * @param message - What failed
21
+ * @param source - `file.ts:line`, when one was recorded
22
+ * @returns The message `okm` prints
23
+ */
24
+ export declare function withLocation(message: string, source: string | undefined): string;
@@ -70,6 +70,21 @@ export type Insert<N extends TableName<S>, S extends AnySchema | undefined = und
70
70
  * @typeParam S - Explicit schema. Omit it to use {@link Register}
71
71
  */
72
72
  export type Update<N extends TableName<S>, S extends AnySchema | undefined = undefined> = ShapeOf<S, N, "~update">;
73
+ /**
74
+ * Insert shape used when validation is on.
75
+ *
76
+ * The fields match {@link Insert}. The optional mark makes the two types
77
+ * distinct, so a checked call can require this shape only while validation
78
+ * is enabled. Guarded fields and the tenant key are already absent.
79
+ *
80
+ * @typeParam N - Table name
81
+ * @typeParam S - Explicit schema. Omit it to use {@link Register}
82
+ */
83
+ export type Input<N extends TableName<S>, S extends AnySchema | undefined = undefined> = Insert<N, S> & InputMark;
84
+ /** Optional mark that distinguishes {@link Input} from {@link Insert}. */
85
+ export type InputMark = {
86
+ readonly "~input"?: true;
87
+ };
73
88
  /**
74
89
  * One phantom on the table named `N`.
75
90
  *
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Cascade checks and partial uniques for `archivable()`.
3
+ *
4
+ * The trait calls this from the schema rewrite, after tenancy widens uniques.
5
+ * `schema()` does not import it.
6
+ */
7
+ import { type AnyTable } from "./table.js";
8
+ /**
9
+ * Makes an archivable table's uniques partial and checks its cascade.
10
+ *
11
+ * Tenancy has already widened uniques. This pass turns those lists into
12
+ * unique indexes filtered on `archived_at is null`, and stores the cascade
13
+ * links the planner reads.
14
+ *
15
+ * @param self - The trait object on the table or the schema
16
+ * @param tables - Tables after the tenancy rewrite
17
+ * @param casing - Schema casing
18
+ * @param schemaTraits - Traits from `schema()`, when any were passed
19
+ * @param cascade - Child tables named on this trait
20
+ * @returns Tables with partial uniques and an archive model where this trait applies
21
+ */
22
+ export declare function rewriteArchivable(self: object, tables: readonly AnyTable[], casing: "snake" | undefined, schemaTraits: readonly object[] | undefined, cascade: readonly string[]): readonly AnyTable[];
@@ -2,9 +2,10 @@
2
2
  * Column builder shared by every Postgres type.
3
3
  *
4
4
  * Modifiers allocate a new builder when called. Importing this module does
5
- * not build a codec table. `.validate()` stays a slot for P26.
5
+ * not build a codec table. `.validate()` stores rules and does not run them.
6
6
  */
7
7
  import { type ReferentialAction } from "../../contracts/catalog/types.js";
8
+ import { type ClientFill } from "../../contracts/generator.js";
8
9
  /** Flags that decide the row, insert, and update shapes of one column. */
9
10
  export type ColumnFlags = {
10
11
  readonly nullable: boolean;
@@ -13,6 +14,8 @@ export type ColumnFlags = {
13
14
  readonly guarded: boolean;
14
15
  readonly hidden: boolean;
15
16
  readonly omitWrite: boolean;
17
+ /** Absent from update. Insert still follows {@link InsertKind}. */
18
+ readonly omitUpdate: boolean;
16
19
  };
17
20
  /** Flags for a required column with no default. */
18
21
  export type PlainFlags = {
@@ -22,8 +25,9 @@ export type PlainFlags = {
22
25
  readonly guarded: false;
23
26
  readonly hidden: false;
24
27
  readonly omitWrite: false;
28
+ readonly omitUpdate: false;
25
29
  };
26
- /** Flags for {@link id}. Insert and update omit it. */
30
+ /** Flags for {@link id} when the database fills the value. Insert and update omit it. */
27
31
  export type IdFlags = {
28
32
  readonly nullable: false;
29
33
  readonly hasDefault: true;
@@ -31,6 +35,21 @@ export type IdFlags = {
31
35
  readonly guarded: true;
32
36
  readonly hidden: false;
33
37
  readonly omitWrite: true;
38
+ readonly omitUpdate: true;
39
+ };
40
+ /**
41
+ * Flags for {@link id} with `default: "none"`.
42
+ *
43
+ * Insert requires the value. Update omits it.
44
+ */
45
+ export type IdSuppliedFlags = {
46
+ readonly nullable: false;
47
+ readonly hasDefault: false;
48
+ readonly generated: false;
49
+ readonly guarded: false;
50
+ readonly hidden: false;
51
+ readonly omitWrite: false;
52
+ readonly omitUpdate: true;
34
53
  };
35
54
  /** Flags for {@link identity}. The database fills the value. */
36
55
  export type IdentityFlags = {
@@ -40,6 +59,7 @@ export type IdentityFlags = {
40
59
  readonly guarded: false;
41
60
  readonly hidden: false;
42
61
  readonly omitWrite: true;
62
+ readonly omitUpdate: true;
43
63
  };
44
64
  /**
45
65
  * Turns one flag on.
@@ -58,6 +78,14 @@ export type FlagTrue<TFlags extends ColumnFlags, K extends keyof ColumnFlags> =
58
78
  export type WithGenerated<TFlags extends ColumnFlags> = {
59
79
  readonly [P in keyof TFlags]: P extends "generated" | "hasDefault" ? true : TFlags[P];
60
80
  };
81
+ /**
82
+ * Omits a column from update and leaves insert unchanged.
83
+ *
84
+ * @typeParam TFlags - Current flags
85
+ */
86
+ export type WithUpdateGuard<TFlags extends ColumnFlags> = {
87
+ readonly [P in keyof TFlags]: P extends "omitUpdate" ? true : TFlags[P];
88
+ };
61
89
  /** How a default expression is spelled in the catalog. */
62
90
  export type SqlForm = "raw" | "quote" | "json" | "jsonb" | "cast";
63
91
  /**
@@ -70,7 +98,14 @@ export type ReferenceModifier = {
70
98
  readonly table: string;
71
99
  readonly onDelete?: ReferentialAction;
72
100
  readonly onUpdate?: ReferentialAction;
101
+ /** Target columns. Several columns make a composite foreign key. */
73
102
  readonly columns?: readonly string[];
103
+ /**
104
+ * Other local columns in the foreign key, after this column.
105
+ *
106
+ * Set when the key is composite. Absent on a single-column reference.
107
+ */
108
+ readonly along?: readonly string[];
74
109
  };
75
110
  /**
76
111
  * Options for {@link ColumnBuilder.references}.
@@ -81,7 +116,7 @@ export type ReferenceOptions = {
81
116
  readonly columns?: readonly string[];
82
117
  };
83
118
  /**
84
- * Validation rules, stored when a later prompt adds `.validate()`.
119
+ * Validation rules stored on the column. Nothing here interprets them.
85
120
  */
86
121
  export type ValidateModifier = {
87
122
  readonly rules: readonly unknown[];
@@ -114,7 +149,7 @@ export type ColumnInsert<TFlags extends ColumnFlags, TValue> = InsertKind<TFlags
114
149
  * @typeParam TFlags - Column flags
115
150
  * @typeParam TValue - Scalar or array value
116
151
  */
117
- export type ColumnUpdate<TFlags extends ColumnFlags, TValue> = InsertKind<TFlags> extends "omit" ? never : TFlags["nullable"] extends true ? TValue | null | undefined : TValue | undefined;
152
+ export type ColumnUpdate<TFlags extends ColumnFlags, TValue> = TFlags["omitUpdate"] extends true ? never : InsertKind<TFlags> extends "omit" ? never : TFlags["nullable"] extends true ? TValue | null | undefined : TValue | undefined;
118
153
  /**
119
154
  * Row shape of a builder.
120
155
  *
@@ -141,6 +176,20 @@ export type ColumnState<TValue> = {
141
176
  readonly hasDefault: boolean;
142
177
  readonly defaultSql: string | undefined;
143
178
  readonly defaultValue: unknown;
179
+ /**
180
+ * Client generator. Absent from the catalog and its hash.
181
+ *
182
+ * The catalog output labels it `client`. Insert fills the column when the
183
+ * caller omits it.
184
+ */
185
+ readonly clientDefault: ClientFill | undefined;
186
+ /** Column collation. Omitted from the catalog when unset. */
187
+ readonly collation: string | undefined;
188
+ /**
189
+ * `implicit` is a bare `t.id()`. `schema({ defaults: { id } })` may replace
190
+ * it. `column` is a choice on that column and wins.
191
+ */
192
+ readonly idSource: "implicit" | "column" | undefined;
144
193
  readonly identity: {
145
194
  readonly always: boolean;
146
195
  } | undefined;
@@ -158,7 +207,10 @@ export type ColumnState<TValue> = {
158
207
  } | undefined;
159
208
  readonly guarded: boolean;
160
209
  readonly hidden: boolean;
210
+ /** Redacted in logs, errors, and `inspect()`. Not part of the catalog hash. */
211
+ readonly sensitive: boolean;
161
212
  readonly omitWrite: boolean;
213
+ readonly omitUpdate: boolean;
162
214
  readonly renamedFrom: string | undefined;
163
215
  readonly sqlName: string | undefined;
164
216
  readonly comment: string | undefined;
@@ -179,6 +231,11 @@ export type ColumnState<TValue> = {
179
231
  readonly decode: (wire: string) => TValue;
180
232
  readonly elementEncode: (value: unknown) => string;
181
233
  readonly elementDecode: (wire: string) => unknown;
234
+ /**
235
+ * Object kinds the codec takes as input, named by `Object.prototype.toString`
236
+ * (`"Array"`, `"Temporal.Instant"`). Absent when the codec takes only scalars.
237
+ */
238
+ readonly accepts: readonly string[] | undefined;
182
239
  };
183
240
  /** Fields a scalar builder sets. Flags are passed beside the codec. */
184
241
  export type OpenColumn<TValue> = {
@@ -189,10 +246,15 @@ export type OpenColumn<TValue> = {
189
246
  readonly guarded: boolean;
190
247
  readonly hidden: boolean;
191
248
  readonly omitWrite: boolean;
249
+ readonly omitUpdate?: boolean;
192
250
  readonly encode: (value: TValue) => string;
193
251
  readonly decode: (wire: string) => TValue;
252
+ readonly accepts?: readonly string[];
194
253
  readonly sqlForm: SqlForm;
195
254
  readonly defaultSql?: string;
255
+ readonly clientDefault?: ClientFill;
256
+ readonly collation?: string;
257
+ readonly idSource?: "implicit" | "column";
196
258
  readonly identity?: {
197
259
  readonly always: boolean;
198
260
  };
@@ -248,12 +310,16 @@ export declare class ColumnBuilder<TValue, TFlags extends ColumnFlags> {
248
310
  */
249
311
  nullable(): ColumnBuilder<TValue, FlagTrue<TFlags, "nullable">>;
250
312
  /**
251
- * Stores a JavaScript default. The catalog receives its SQL spelling.
313
+ * Stores a literal database default, or a client generator.
314
+ *
315
+ * A literal is written into the catalog as SQL. A function is a client
316
+ * generator: insert fills the column when it is omitted, and the catalog
317
+ * stores no default. Pass `uuidv4`, `uuidv7`, `okid(...)`, or any function.
252
318
  *
253
- * @param value - Default value
319
+ * @param value - Literal default, or a function that returns one value
254
320
  * @returns The same column, with a default
255
321
  */
256
- default(value: TFlags["nullable"] extends true ? TValue | null : TValue): ColumnBuilder<TValue, FlagTrue<TFlags, "hasDefault">>;
322
+ default(value: (TFlags["nullable"] extends true ? TValue | null : TValue) | (() => TValue)): ColumnBuilder<TValue, FlagTrue<TFlags, "hasDefault">>;
257
323
  /**
258
324
  * Stores a SQL default expression as written.
259
325
  *
@@ -262,14 +328,26 @@ export declare class ColumnBuilder<TValue, TFlags extends ColumnFlags> {
262
328
  */
263
329
  defaultSql(expression: string): ColumnBuilder<TValue, FlagTrue<TFlags, "hasDefault">>;
264
330
  /**
265
- * Records a unique constraint. Tenancy later reads `global`.
331
+ * Makes this column the table's primary key.
332
+ *
333
+ * Insert still accepts the value. Update omits it. A composite key is the
334
+ * `primaryKey` option on `table()`, not a second call.
335
+ *
336
+ * @returns The same column, as a primary key
337
+ */
338
+ primaryKey(): ColumnBuilder<TValue, WithUpdateGuard<TFlags>>;
339
+ /**
340
+ * Records a unique constraint.
341
+ *
342
+ * On a tenant table the key is included, unless `global` names a reason.
343
+ * `global: "reason"` and `{ global: true, reason }` are the same opt-out.
266
344
  *
267
345
  * @param options - Exemption reason, and whether the unique ignores the tenant key
268
346
  * @returns The same column
269
347
  */
270
348
  unique(options?: {
271
349
  readonly reason?: string;
272
- readonly global?: boolean;
350
+ readonly global?: boolean | string;
273
351
  }): ColumnBuilder<TValue, TFlags>;
274
352
  /**
275
353
  * Narrows a string column to a literal union.
@@ -303,9 +381,33 @@ export declare class ColumnBuilder<TValue, TFlags extends ColumnFlags> {
303
381
  /**
304
382
  * Excludes the column from the default row.
305
383
  *
384
+ * A named `select` still returns it. Includes never do.
385
+ *
306
386
  * @returns The same column, hidden
307
387
  */
308
388
  hidden(): ColumnBuilder<TValue, FlagTrue<TFlags, "hidden">>;
389
+ /**
390
+ * Redacts the value in logs, errors, and `inspect()`.
391
+ *
392
+ * The stored value is unchanged. A read that selects the column still
393
+ * returns it. The catalog hash does not include this flag.
394
+ *
395
+ * @returns The same column, sensitive
396
+ */
397
+ sensitive(): ColumnBuilder<TValue, TFlags>;
398
+ /**
399
+ * Stores validation rules or one Standard Schema.
400
+ *
401
+ * The rules are stored. They run only when validation is enabled and the
402
+ * engine has loaded. A field listed here and in the table `validate`
403
+ * section is OKM1030, reported by `okm check`.
404
+ *
405
+ * @param rules - Rule list, or one Standard Schema
406
+ * @returns The same column, with the rules stored
407
+ */
408
+ validate(rules: readonly unknown[] | {
409
+ readonly "~standard": unknown;
410
+ }): ColumnBuilder<TValue, TFlags>;
309
411
  /**
310
412
  * Points this column at another table.
311
413
  *
@@ -384,3 +486,18 @@ export declare function formatType(baseType: string, dims: number): string;
384
486
  * @returns A default expression
385
487
  */
386
488
  export declare function sqlOf<TValue>(state: ColumnState<TValue>, value: TValue): string;
489
+ /**
490
+ * Returns a column with a cleared unique flag or a replaced reference.
491
+ *
492
+ * `okmodel/tenancy` uses this while rewriting tables. `schema()` then compiles
493
+ * the result with the ordinary unique and foreign-key paths.
494
+ *
495
+ * @param column - Column to copy
496
+ * @param patch - Unique or primary flag to drop, or the reference to store
497
+ * @returns A new column builder
498
+ */
499
+ export declare function retarget<TValue, TFlags extends ColumnFlags>(column: ColumnBuilder<TValue, TFlags>, patch: {
500
+ readonly dropUnique?: boolean;
501
+ readonly dropPrimary?: boolean;
502
+ readonly references?: ReferenceModifier;
503
+ }): ColumnBuilder<TValue, TFlags>;
@@ -12,6 +12,7 @@ export type CompilableColumn = {
12
12
  readonly dims: number;
13
13
  readonly nullable: boolean;
14
14
  readonly defaultSql: string | undefined;
15
+ readonly collation: string | undefined;
15
16
  readonly identity: {
16
17
  readonly always: boolean;
17
18
  } | undefined;
@@ -16,6 +16,12 @@ export declare function custom<TValue>(spec: {
16
16
  readonly sqlType: string;
17
17
  readonly encode: (value: TValue) => string;
18
18
  readonly decode: (wire: string) => TValue;
19
+ /**
20
+ * Object kinds the codec takes, as `Object.prototype.toString` names them: `"Object"`
21
+ * for a plain object, `"Array"`, `"Temporal.Instant"`. Omit it when `TValue` is a
22
+ * scalar: every object is then rejected (OKM1121).
23
+ */
24
+ readonly accepts?: readonly string[];
19
25
  readonly extension?: string;
20
26
  readonly sqlForm?: SqlForm;
21
27
  }): ColumnBuilder<TValue, PlainFlags>;
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Turns an allowlisted request object into `where` and `orderBy`.
3
+ *
4
+ * Loaded the first time `parse()` is called. `filters()` validates the spec
5
+ * before this module exists.
6
+ */
7
+ import type { ParsedFilters } from "./table.js";
8
+ /**
9
+ * Reads one request object.
10
+ *
11
+ * A plain value is equality when `eq` is allowlisted. `sort` is a field name
12
+ * from the sort list. JSON cannot add an operator.
13
+ *
14
+ * @param allow - Fields and the operators each one accepts
15
+ * @param sort - Fields a caller may sort by
16
+ * @param query - One request object
17
+ * @returns Filters a caller can spread into `find`
18
+ */
19
+ export declare function parseQuery(allow: Readonly<Record<string, readonly string[]>>, sort: readonly string[], query: unknown): ParsedFilters;
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Allowlisted filters. The checks run when `filters()` is called.
3
+ *
4
+ * A hidden field in `allow`, `sort`, or `relations` is OKM1123. The parser
5
+ * loads on the first `parse()`.
6
+ */
7
+ import type { FilterSpec, ParsedFilters } from "./table.js";
8
+ /**
9
+ * Checks an allowlist and returns `parse`.
10
+ *
11
+ * @param table - Table the filters belong to
12
+ * @param relations - Relation calls stored on the table, when it has any
13
+ * @param spec - Allow, sort, and relation fields
14
+ * @param hiddenFields - `table.field` keys recorded while tables were defined
15
+ * @returns A parser for one request object
16
+ */
17
+ export declare function openFilters(table: string, relations: unknown, spec: FilterSpec, hiddenFields: ReadonlySet<string>): {
18
+ parse(query: unknown): Promise<ParsedFilters>;
19
+ };
@@ -6,13 +6,14 @@
6
6
  */
7
7
  export { schema, type BuiltSchema, type SchemaCodecs, type SchemaInput, type SchemaRequires, } from "./schema.js";
8
8
  export { index, sql, table, type AnyTable, type ColumnHandle, type IndexCall, type SqlText, type SqlValue, type Table, type TableOptions, } from "./table.js";
9
+ export type { PresetQuery } from "./preset.js";
9
10
  export { custom } from "./custom.js";
10
11
  export { ColumnBuilder } from "./column.js";
11
12
  export type { ArrayOf, ColumnFlags, ColumnInsert, ColumnInsertOf, ColumnRow, ColumnRowOf, ColumnUpdate, ColumnUpdateOf, FlagTrue, IdFlags, IdentityFlags, PlainFlags, ReferenceModifier, ReferenceOptions, SqlForm, ValidateModifier, WithGenerated, } from "./column.js";
12
13
  export { bigint, identity, integer, smallint, type BigintAs, type BigintValue } from "./integer.js";
13
14
  export { double, numeric, real, type NumericAs, type NumericValue } from "./decimal.js";
14
15
  export { boolean, bytea } from "./bool.js";
15
- export { json, jsonb, jsonReplacer } from "./json.js";
16
+ export { jsonb, jsonReplacer } from "./json.js";
16
17
  export { id, uuid } from "./keys.js";
17
18
  export { char, citext, text, varchar } from "./text.js";
18
19
  export { date, interval, time, timestamp, timestamptz, timetz } from "./time.js";
@@ -23,7 +24,10 @@ export { line, point, type Line, type Point } from "./geometry.js";
23
24
  export { ltree, tsvector } from "./search.js";
24
25
  export { domain, enumColumn as enum } from "./enum.js";
25
26
  export { t } from "./namespace.js";
27
+ export * as arr from "./ops/arr-ns.js";
28
+ export * as json from "./ops/json-ns.js";
26
29
  export { between } from "./ops/between.js";
30
+ export { containedBy } from "./ops/containedBy.js";
27
31
  export { contains } from "./ops/contains.js";
28
32
  export { endsWith } from "./ops/endsWith.js";
29
33
  export { eq } from "./ops/eq.js";
@@ -32,14 +36,19 @@ export { gt } from "./ops/gt.js";
32
36
  export { inc } from "./ops/inc.js";
33
37
  export { gte } from "./ops/gte.js";
34
38
  export { has } from "./ops/has.js";
39
+ export { hasAnyKey } from "./ops/hasAnyKey.js";
40
+ export { hasKey } from "./ops/hasKey.js";
35
41
  export { ilike } from "./ops/ilike.js";
36
42
  export { inList } from "./ops/inList.js";
37
43
  export { like } from "./ops/like.js";
44
+ export { matches } from "./ops/matches.js";
38
45
  export { lt } from "./ops/lt.js";
39
46
  export { lte } from "./ops/lte.js";
40
47
  export { none } from "./ops/none.js";
41
48
  export { not } from "./ops/not.js";
42
49
  export { notIn } from "./ops/notIn.js";
43
50
  export { or } from "./ops/or.js";
51
+ export { overlaps } from "./ops/overlaps.js";
52
+ export { path } from "./ops/path.js";
44
53
  export { startsWith } from "./ops/startsWith.js";
45
- export { many, one, type ManyRelation, type OneRelation, type RelationCall } from "./relations.js";
54
+ export { many, manyThrough, one, type ManyRelation, type ManyThroughRelation, type OneRelation, type RelationCall, } from "./relations.js";