@bakery-framework/orm 2.2.0 → 2.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/orm",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Bakery database layer: adapters, query builder, schema sync and backup.",
   "keywords": [
     "bakery",
@@ -56,6 +56,6 @@
     "bun": ">=1.4.0"
   },
   "dependencies": {
-    "@bakery-framework/core": "^2.2.0"
+    "@bakery-framework/core": "^2.2.2"
   }
 }

package/src/array-value.ts

@@ -21,6 +21,50 @@ export function isArrayValue(value: unknown): value is ArrayValue {
   return value instanceof ArrayValue
 }
 
+declare const PG_ARRAY: unique symbol
+
+/**
+ * The row type of a `Field.Array` column: an array, marked as a Postgres
+ * array so the write types can tell it from an array of another kind (a
+ * `jsonb` column typed `number[]`, which takes a plain array as JSON).
+ *
+ * The mark exists only in the types, and it is optional, so a plain array is
+ * a `PgArray` as it is: a read, a row built by hand and a test's
+ * `toEqual(['a'])` type as they would against `T[]`. A required mark broke
+ * all three. `Writable` reads the mark by its key rather than by
+ * assignability, since every plain array is assignable to an optional mark.
+ */
+export type PgArray<T> = T[] & { readonly [PG_ARRAY]?: T }
+
+/**
+ * What a write to a column of row type `V` accepts. A Postgres array column
+ * takes `DB.array()` of its elements and nothing else, since Bun cannot bind
+ * a plain array to one (see `ArrayValue`). Every other column takes its row
+ * type, `any` included: an unregistered schema stays permissive.
+ */
+export type Writable<V> = 0 extends 1 & V
+  ? V
+  : V extends readonly (infer E)[]
+    ? typeof PG_ARRAY extends keyof V
+      ? ArrayValue<E>
+      : V
+    : V
+
+/** A row's columns as a write accepts them. */
+export type WritableRow<R> = { [K in keyof R]: Writable<R[K]> }
+
+/**
+ * What an `INSERT` accepts for a row of type `Row`: its columns as a write
+ * takes them, the `Optional` ones optional. The one definition behind both
+ * `Mutation.InsertSchema` (a schema registered by declaration merging) and
+ * `InsertOf` (a `table()` value), so the two cannot disagree.
+ */
+export type InsertRecord<Row, Optional extends keyof Row> = Omit<
+  WritableRow<Row>,
+  Optional
+> &
+  Partial<Pick<WritableRow<Row>, Optional>>
+
 /**
  * The text of a Postgres array literal for `values`: `{"a","b c",NULL}`.
  *

package/src/define.ts

@@ -1,3 +1,4 @@
+import type { InsertRecord } from './array-value'
 import type {
   ExtractOptionals,
   ExtractTableTypes,
@@ -368,13 +369,7 @@ export type RowOf<T extends TableRef> = ExtractTableTypes<
  *     export type NewUser = InsertOf<typeof users>
  *     //     ^ { name: string; id?: number; createdAt?: number }
  */
-export type InsertOf<T extends TableRef> = Omit<
+export type InsertOf<T extends TableRef> = InsertRecord<
   RowOf<T>,
   ExtractOptionals<{ t: T['__columns'] }, 't'> & keyof RowOf<T>
-> &
-  Partial<
-    Pick<
-      RowOf<T>,
-      ExtractOptionals<{ t: T['__columns'] }, 't'> & keyof RowOf<T>
-    >
-  >
+>

package/src/field.ts

@@ -1,4 +1,5 @@
 import { throws } from '@bakery-framework/core/utils/common'
+import type { PgArray } from './array-value'
 import type { DataTypes, TableDef } from './schema-util'
 import type * as SyncTypes from './sync/types'
 
@@ -382,15 +383,17 @@ export const Field = {
     if (options.nullable) def.nullable = true
     return def
   }) as {
-    <E extends ArrayElement>(element: E): TableDef<ElementOf<E>[], false, false>
+    <E extends ArrayElement>(
+      element: E,
+    ): TableDef<PgArray<ElementOf<E>>, false, false>
     <E extends ArrayElement>(
       element: E,
       options: { optional: true },
-    ): TableDef<ElementOf<E>[], false, true>
+    ): TableDef<PgArray<ElementOf<E>>, false, true>
     <E extends ArrayElement>(
       element: E,
       options: { nullable: true; optional?: true },
-    ): TableDef<ElementOf<E>[] | null, true, true>
+    ): TableDef<PgArray<ElementOf<E>> | null, true, true>
   },
 
   /** True/false: `BOOLEAN` on Postgres, `TINYINT(1)` on MySQL. */

package/src/index.ts

@@ -21,6 +21,12 @@ export type {
  * module that can open a database connection.
  */
 export { getQueryObserver, setQueryObserver } from './adapters/observe'
+/**
+ * The row type of a `Field.Array` column, exported because row types name it:
+ * a plain array to read, `DB.array()` to write. `Field.Sql<PgArray<string>>`
+ * declares an array the same way for a SQL type `Field.Array` does not spell.
+ */
+export type { PgArray } from './array-value'
 export type {
   InferOptionals,
   InferSchema,

package/src/orm/mutation.ts

@@ -1,6 +1,7 @@
 import { Try } from '@bakery-framework/core/utils'
 import { throws } from '@bakery-framework/core/utils/common'
 import { DEFAULT_MAX_QUERY_PARAMS, type SQLAdapter } from '../adapters'
+import type { InsertRecord } from '../array-value'
 import { getActiveDb, txStorage } from '../connection'
 import type {
   AppViews,
@@ -52,10 +53,7 @@ export namespace Mutation {
   }
 
   export type InsertSchema<T extends Tables> = T extends keyof DBSchema
-    ? Prettify<
-        Omit<DBSchema[T], ValidOptionals<T>> &
-          Partial<Pick<DBSchema[T], ValidOptionals<T>>>
-      >
+    ? Prettify<InsertRecord<DBSchema[T], ValidOptionals<T>>>
     : MapOf<unknown>
 
   export type UpdateSchema<T extends Tables> = Partial<InsertSchema<T>>

package/src/orm/query.ts

@@ -136,6 +136,7 @@ export namespace DB {
     | schemaColumnRef<C>
     | QBRaw
     | QBObject
+    | ArrayValue
     | string
     | number
     | boolean