effect-qb 0.17.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-qb",
-  "version": "0.17.0",
+  "version": "0.20.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,10 @@
     "README.md"
   ],
   "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
     "./postgres": {
       "types": "./src/postgres.ts",
       "import": "./dist/postgres.js"
@@ -40,6 +44,7 @@
     "./package.json": "./package.json"
   },
   "imports": {
+    "#standard": "./src/standard.ts",
     "#postgres": "./src/postgres.ts",
     "#mysql": "./src/mysql.ts",
     "#sqlite": "./src/sqlite.ts",
@@ -57,9 +62,9 @@
     "@typescript/native-preview": "beta"
   },
   "dependencies": {
-    "@effect/experimental": "^0.57.0",
-    "@effect/sql": "^0.48.0",
-    "effect": "^3.19.3",
     "pgsql-ast-parser": "^12.0.2"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-beta.98"
   }
 }

package/src/casing.ts

@@ -0,0 +1,71 @@
+import * as InternalCasing from "./internal/casing.js"
+import * as BaseTable from "./internal/table.js"
+import * as Table from "./standard/table.js"
+
+export type Style = InternalCasing.Style
+export type Options = InternalCasing.Options
+export type Input = Options | Style
+
+export interface TableFactory {
+  readonly table: typeof Table.make
+  readonly [InternalCasing.TypeId]: InternalCasing.State
+  readonly withCasing: (options: Input) => TableFactory
+}
+
+type CasingTarget =
+  | BaseTable.TableDefinition<any, any, any, any, any>
+  | {
+      readonly [InternalCasing.TypeId]: InternalCasing.State
+      readonly withCasing: (options: Options) => CasingTarget
+    }
+
+const isTable = (value: unknown): value is BaseTable.TableDefinition<any, any, any, any, any> =>
+  typeof value === "object" && value !== null && BaseTable.TypeId in value
+
+const allCategories = (style: Style): Options => ({
+  tables: style,
+  columns: style,
+  schemas: style,
+  indexes: style,
+  constraints: style,
+  types: style,
+  sequences: style
+})
+
+const normalize = (input: Input): Options =>
+  typeof input === "string" || typeof input === "function" ? allCategories(input) : input
+
+export function withCasing(options: Style): <Value extends CasingTarget>(value: Value) => Value
+export function withCasing(options: Options): <Value extends CasingTarget>(value: Value) => Value
+export function withCasing(options: Input) {
+  return <Value extends CasingTarget>(value: Value): Value => {
+    const normalized = normalize(options)
+    if (isTable(value)) {
+      return BaseTable.withCasing(value, normalized) as Value
+    }
+    return (value as Exclude<CasingTarget, BaseTable.TableDefinition<any, any, any, any, any>>).withCasing(normalized) as Value
+  }
+}
+
+export function make(options: Style): TableFactory
+export function make(options: Options): TableFactory
+export function make(options: Input): TableFactory {
+  const normalized = normalize(options)
+  const withFactoryCasing = withCasing(normalized)
+  const table = ((name: string, fields: any, schemaName?: string) =>
+    schemaName === undefined
+      ? Table.make(name, fields).pipe(withFactoryCasing)
+      : Table.make(name, fields, schemaName).pipe(withFactoryCasing)) as typeof Table.make
+  const factory = {
+    table,
+    [InternalCasing.TypeId]: {
+      casing: normalized
+    },
+    withCasing: (override: Input) => make(InternalCasing.merge(normalized, normalize(override)) ?? {})
+  }
+  return factory
+}
+
+export const apply = InternalCasing.apply
+export const applyCategory = InternalCasing.applyCategory
+export const merge = InternalCasing.merge

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./standard.js"
+export * as Casing from "./casing.js"

package/src/internal/casing.ts

@@ -0,0 +1,89 @@
+export const TypeId: unique symbol = Symbol.for("effect-qb/Casing")
+
+export type Style =
+  | "preserve"
+  | "snake_case"
+  | "camelCase"
+  | "PascalCase"
+  | "kebab-case"
+  | "SCREAMING_SNAKE_CASE"
+  | ((name: string) => string)
+
+export interface Options {
+  readonly tables?: Style
+  readonly columns?: Style
+  readonly schemas?: Style
+  readonly indexes?: Style
+  readonly constraints?: Style
+  readonly types?: Style
+  readonly sequences?: Style
+}
+
+export type Category = keyof Options
+
+export interface State {
+  readonly casing?: Options
+}
+
+export const merge = (
+  base: Options | undefined,
+  override: Options | undefined
+): Options | undefined => {
+  if (base === undefined) {
+    return override
+  }
+  if (override === undefined) {
+    return base
+  }
+  return { ...base, ...override }
+}
+
+const words = (name: string): readonly string[] =>
+  name
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .split(/[^A-Za-z0-9]+/)
+    .filter((part) => part.length > 0)
+
+const capitalize = (value: string): string =>
+  value.length === 0 ? value : `${value[0]!.toUpperCase()}${value.slice(1)}`
+
+const lowerWords = (name: string): readonly string[] =>
+  words(name).map((part) => part.toLowerCase())
+
+const applyNamedStyle = (style: Exclude<Style, (name: string) => string>, name: string): string => {
+  switch (style) {
+    case "preserve":
+      return name
+    case "snake_case":
+      return lowerWords(name).join("_")
+    case "camelCase": {
+      const parts = lowerWords(name)
+      const [head, ...tail] = parts
+      return head === undefined ? "" : `${head}${tail.map(capitalize).join("")}`
+    }
+    case "PascalCase":
+      return lowerWords(name).map(capitalize).join("")
+    case "kebab-case":
+      return lowerWords(name).join("-")
+    case "SCREAMING_SNAKE_CASE":
+      return lowerWords(name).join("_").toUpperCase()
+  }
+}
+
+export const apply = (
+  style: Style | undefined,
+  name: string
+): string => {
+  if (style === undefined) {
+    return name
+  }
+  return typeof style === "function" ? style(name) : applyNamedStyle(style, name)
+}
+
+export const applyCategory = (
+  options: Options | undefined,
+  category: Category,
+  name: string
+): string => apply(options?.[category], name)
+

package/src/internal/coercion/rules.ts

@@ -1,5 +1,11 @@
 import type * as Expression from "../scalar.js"
-import type { CanCastDbType as LookupCanCastDbType, CanCompareDbTypes as LookupCanCompareDbTypes, CanContainDbTypes as LookupCanContainDbTypes, CanTextuallyCoerceDbType as LookupCanTextuallyCoerceDbType } from "../datatypes/lookup.js"
+import type {
+  CanCastDbType as LookupCanCastDbType,
+  CanCompareDbTypes as LookupCanCompareDbTypes,
+  CanContainDbTypes as LookupCanContainDbTypes,
+  CanImplicitlyConvertDbType as LookupCanImplicitlyConvertDbType,
+  CanTextuallyCoerceDbType as LookupCanTextuallyCoerceDbType
+} from "../datatypes/lookup.js"
 
 export type CanCompareDbTypes<
   Left extends Expression.DbType.Any,
@@ -18,6 +24,12 @@ export type CanTextuallyCoerceDbType<
   Dialect extends string
 > = LookupCanTextuallyCoerceDbType<Db, Dialect>
 
+export type CanImplicitlyConvertDbType<
+  Source extends Expression.DbType.Any,
+  Target extends Expression.DbType.Any,
+  Dialect extends string
+> = LookupCanImplicitlyConvertDbType<Source, Target, Dialect>
+
 export type CanCastDbType<
   Source extends Expression.DbType.Any,
   Target extends Expression.DbType.Any,

package/src/internal/column-state.d.ts

@@ -70,7 +70,7 @@ export interface ColumnState<Select, Insert, Update, Db extends Expression.DbTyp
 export interface ColumnDefinition<Select, Insert, Update, Db extends Expression.DbType.Any, Nullable extends boolean, HasDefault extends boolean, Generated extends boolean, PrimaryKey extends boolean, Unique extends boolean, Ref, Dependencies extends Expression.BindingId = never> extends Pipeable, Expression.Scalar<Select, Db, Nullable extends true ? "maybe" : "never", Db["dialect"], "scalar", Dependencies> {
     readonly pipe: Pipeable["pipe"];
     readonly [ColumnTypeId]: ColumnState<Select, Insert, Update, Db, Nullable, HasDefault, Generated, PrimaryKey, Unique, Ref, Dependencies>;
-    readonly schema: Schema.Schema<NonNullable<Select>, any, any>;
+    readonly schema: Schema.Schema<NonNullable<Select>>;
     readonly metadata: {
         readonly dbType: Db;
         readonly nullable: Nullable;
@@ -111,7 +111,7 @@ export type AnyColumnDefinition = ColumnDefinition<any, any, any, Expression.DbT
 /** Convenience alias for any bound column. */
 export type AnyBoundColumn = BoundColumn<any, any, any, Expression.DbType.Any, boolean, boolean, boolean, boolean, boolean, any, string, string, string>;
 /** Constructs a runtime column-definition object from schema and metadata. */
-export declare const makeColumnDefinition: <Select, Insert, Update, Db extends Expression.DbType.Any, Nullable extends boolean, HasDefault extends boolean, Generated extends boolean, PrimaryKey extends boolean, Unique extends boolean, Ref, Dependencies extends string = never>(schema: Schema.Schema<NonNullable<Select>, any, any>, metadata: {
+export declare const makeColumnDefinition: <Select, Insert, Update, Db extends Expression.DbType.Any, Nullable extends boolean, HasDefault extends boolean, Generated extends boolean, PrimaryKey extends boolean, Unique extends boolean, Ref, Dependencies extends string = never>(schema: Schema.Schema<NonNullable<Select>>, metadata: {
     readonly dbType: Db;
     readonly nullable: Nullable;
     readonly hasDefault: HasDefault;
@@ -135,7 +135,7 @@ export declare const makeColumnDefinition: <Select, Insert, Update, Db extends E
     } | undefined;
 }) => ColumnDefinition<Select, Insert, Update, Db, Nullable, HasDefault, Generated, PrimaryKey, Unique, Ref, Dependencies>;
 export declare const remapColumnDefinition: <Select, Insert, Update, Db extends Expression.DbType.Any, Nullable extends boolean, HasDefault extends boolean, Generated extends boolean, PrimaryKey extends boolean, Unique extends boolean, Ref, Dependencies extends string = never>(column: ColumnDefinition<Select, Insert, Update, Db, Nullable, HasDefault, Generated, PrimaryKey, Unique, Ref, Dependencies>, options?: {
-    readonly schema?: Schema.Schema.Any | undefined;
+    readonly schema?: Schema.Top | undefined;
     readonly metadata?: {
         readonly dbType: Db;
         readonly nullable: Nullable;

package/src/internal/column-state.ts

@@ -4,6 +4,8 @@ import * as Schema from "effect/Schema"
 
 import * as Expression from "./scalar.js"
 import * as ExpressionAst from "./expression-ast.js"
+import { withJsonPathAccess, type WithJsonPathAccess } from "./json/path-access.js"
+import type * as Casing from "./casing.js"
 import type * as SchemaExpression from "./schema-expression.js"
 
 /** Symbol used to attach column-definition metadata. */
@@ -123,7 +125,7 @@ export interface ColumnDefinition<
     Ref,
     Dependencies
   >
-  readonly schema: Schema.Schema<NonNullable<Select>, any, any>
+  readonly schema: Schema.Schema<NonNullable<Select>>
   readonly metadata: {
     readonly dbType: Db
     readonly nullable: Nullable
@@ -183,6 +185,7 @@ export interface BoundColumn<
     readonly columnName: ColumnName
     readonly baseTableName: BaseTableName
     readonly schemaName?: string
+    readonly casing?: Casing.Options
   }
   readonly [Expression.TypeId]: Expression.State<
     Select,
@@ -227,7 +230,7 @@ export type AnyBoundColumn = BoundColumn<
 >
 
 const ColumnProto = {
-  pipe(this: unknown) {
+  pipe(this: Pipeable) {
     return pipeArguments(this, arguments)
   }
 }
@@ -236,7 +239,7 @@ const attachPipe = <Value extends object>(value: Value): Value => {
   Object.defineProperty(value, "pipe", {
     configurable: true,
     writable: true,
-    value: function(this: unknown) {
+    value: function(this: Value) {
       return pipeArguments(value, arguments)
     }
   })
@@ -257,7 +260,7 @@ export const makeColumnDefinition = <
   Ref,
   Dependencies extends Expression.BindingId = never
 >(
-  schema: Schema.Schema<NonNullable<Select>, any, any>,
+  schema: Schema.Schema<NonNullable<Select>>,
   metadata: ColumnDefinition<
     Select,
     Insert,
@@ -271,7 +274,7 @@ export const makeColumnDefinition = <
     Ref,
     Dependencies
   >["metadata"]
-): ColumnDefinition<
+): WithJsonPathAccess<ColumnDefinition<
   Select,
   Insert,
   Update,
@@ -283,7 +286,7 @@ export const makeColumnDefinition = <
   Unique,
   Ref,
   Dependencies
-> => {
+>> => {
   const column = attachPipe(Object.create(ColumnProto))
   column.schema = schema
   column.metadata = metadata
@@ -315,7 +318,7 @@ export const makeColumnDefinition = <
     identity: metadata.identity,
     enum: metadata.enum
   }
-  return column
+  return withJsonPathAccess(column)
 }
 
 export const remapColumnDefinition = <
@@ -345,7 +348,7 @@ export const remapColumnDefinition = <
     Dependencies
   >,
   options: {
-    readonly schema?: Schema.Schema.Any
+    readonly schema?: Schema.Top
     readonly metadata?: ColumnDefinition<
       Select,
       Insert,
@@ -360,7 +363,7 @@ export const remapColumnDefinition = <
       Dependencies
     >["metadata"]
   } = {}
-): ColumnDefinition<
+): WithJsonPathAccess<ColumnDefinition<
   Select,
   Insert,
   Update,
@@ -372,7 +375,7 @@ export const remapColumnDefinition = <
   Unique,
   Ref,
   Dependencies
-> => {
+>> => {
   const schema = options.schema ?? column.schema
   const metadata = options.metadata ?? column.metadata
   const next = attachPipe(Object.create(ColumnProto))
@@ -407,21 +410,22 @@ export const remapColumnDefinition = <
     enum: metadata.enum
   }
   if (ExpressionAst.TypeId in column) {
-    next[ExpressionAst.TypeId] = (column as unknown as {
+    next[ExpressionAst.TypeId] = (column as {
       readonly [ExpressionAst.TypeId]: ExpressionAst.Any
     })[ExpressionAst.TypeId]
   }
   if (BoundColumnTypeId in column) {
-    next[BoundColumnTypeId] = (column as unknown as {
+    next[BoundColumnTypeId] = (column as {
       readonly [BoundColumnTypeId]: {
         readonly tableName: string
         readonly columnName: string
         readonly baseTableName: string
         readonly schemaName?: string
+        readonly casing?: Casing.Options
       }
     })[BoundColumnTypeId]
   }
-  return next
+  return withJsonPathAccess(next)
 }
 
 /** Attaches table/column provenance to an existing column definition. */
@@ -436,7 +440,8 @@ export const bindColumn = <
   columnName: ColumnName,
   column: Column,
   baseTableName: BaseTableName,
-  schemaName?: SchemaName
+  schemaName?: SchemaName,
+  casing?: Casing.Options
 ): BoundColumnFrom<Column, TableName, ColumnName, BaseTableName> => {
   const brandName = `${tableName}.${columnName}`
   const schema = column.metadata.brand === true
@@ -467,9 +472,10 @@ export const bindColumn = <
     tableName,
     columnName,
     baseTableName,
-    schemaName
+    schemaName,
+    casing
   }
-  return bound
+  return withJsonPathAccess(bound) as BoundColumnFrom<Column, TableName, ColumnName, BaseTableName>
 }
 
 /** Extracts the internal state record for a column. */
@@ -508,7 +514,7 @@ export type BoundColumnFrom<
   TableName extends string,
   ColumnName extends string,
   BaseTableName extends string = TableName
-> = BoundColumn<
+> = WithJsonPathAccess<BoundColumn<
   Column["metadata"]["brand"] extends true
     ? BrandedValue<SelectType<Column>, `${TableName}.${ColumnName}`>
     : SelectType<Column>,
@@ -528,4 +534,4 @@ export type BoundColumnFrom<
   TableName,
   ColumnName,
   BaseTableName
->
+>>

package/src/internal/column.ts

@@ -42,6 +42,7 @@ import {
   type SelectType,
   type UpdateType
 } from "./column-state.js"
+import type { NonEmptyStringInput } from "./table-options.js"
 
 type ReferentialAction = "noAction" | "restrict" | "cascade" | "setNull" | "setDefault"
 
@@ -223,23 +224,53 @@ type ForeignKeyOptions<Target extends AnyBoundColumn> = {
   readonly initiallyDeferred?: boolean
 }
 
+type NonEmptyOptionNameInput<Options> = Options extends { readonly name: infer Name extends string }
+  ? NonEmptyStringInput<Name> extends never ? never : unknown
+  : unknown
+
+type NonEmptyStringArrayInput<Values extends readonly string[]> =
+  [Extract<Values[number], "">] extends [never] ? unknown : never
+
+type NonEmptyIndexMethodInput<Options> = Options extends { readonly method: infer Method extends string }
+  ? NonEmptyStringInput<Method> extends never ? never : unknown
+  : unknown
+
+type NonEmptyIndexIncludeInput<Options> = Options extends { readonly include: infer Include extends readonly string[] }
+  ? NonEmptyStringArrayInput<Include>
+  : unknown
+
+type NonEmptyIndexOperatorClassInput<Options> = Options extends { readonly operatorClass: infer OperatorClass extends string }
+  ? NonEmptyStringInput<OperatorClass> extends never ? never : unknown
+  : unknown
+
+type NonEmptyIndexCollationInput<Options> = Options extends { readonly collation: infer Collation extends string }
+  ? NonEmptyStringInput<Collation> extends never ? never : unknown
+  : unknown
+
+type NonEmptyIndexMetadataInput<Options> =
+  & NonEmptyOptionNameInput<Options>
+  & NonEmptyIndexMethodInput<Options>
+  & NonEmptyIndexIncludeInput<Options>
+  & NonEmptyIndexOperatorClassInput<Options>
+  & NonEmptyIndexCollationInput<Options>
+
 type SchemaCompatibleColumn<
   Column extends AnyColumnDefinition,
-  SchemaType extends Schema.Schema.Any
-> = [BaseSelectType<Column>] extends [Schema.Schema.Encoded<SchemaType>]
+  SchemaType extends Schema.Top
+> = [BaseSelectType<Column>] extends [Schema.Codec.Encoded<SchemaType>]
   ? Column
   : never
 
 type ColumnSchemaOutput<
   Column extends AnyColumnDefinition,
-  SchemaType extends Schema.Schema.Any
+  SchemaType extends Schema.Top
 > = IsNullable<Column> extends true
   ? Schema.Schema.Type<SchemaType> | null
   : Schema.Schema.Type<SchemaType>
 
 type ColumnWithSchema<
   Column extends AnyColumnDefinition,
-  SchemaType extends Schema.Schema.Any
+  SchemaType extends Schema.Top
 > = ColumnDefinition<
   ColumnSchemaOutput<Column, SchemaType>,
   ColumnSchemaOutput<Column, SchemaType>,
@@ -376,7 +407,7 @@ const isColumnDefinitionValue = (value: unknown): value is AnyColumnDefinition =
   typeof value === "object" && value !== null && ColumnTypeId in value
 
 const primitive = <Type, Db extends Expression.DbType.Any>(
-  schema: Schema.Schema<Type, any, any>,
+  schema: Schema.Schema<Type>,
   dbType: Db
 ): ColumnDefinition<Type, Type, Type, Db, false, false, false, false, false, undefined> =>
   makeColumnDefinition(schema as Schema.Schema<NonNullable<Type>>, {
@@ -401,7 +432,7 @@ type ColumnModule<
   JsonKind extends string
 > = {
   readonly custom: <
-    SchemaType extends Schema.Schema.Any,
+    SchemaType extends Schema.Top,
     Db extends Expression.DbType.Any
   >(
     schema: SchemaType,
@@ -425,7 +456,7 @@ type ColumnModule<
   readonly boolean: () => ColumnDefinition<boolean, boolean, boolean, Expression.DbType.Base<Dialect, BooleanKind>, false, false, false, false, false, undefined>
   readonly date: () => ColumnDefinition<LocalDateString, LocalDateString, LocalDateString, Expression.DbType.Base<Dialect, DateKind>, false, false, false, false, false, undefined>
   readonly timestamp: () => ColumnDefinition<LocalDateTimeString, LocalDateTimeString, LocalDateTimeString, Expression.DbType.Base<Dialect, TimestampKind>, false, false, false, false, false, undefined>
-  readonly json: <SchemaType extends Schema.Schema.Any>(
+  readonly json: <SchemaType extends Schema.Top>(
     schema: SchemaType
   ) => ColumnDefinition<
     Schema.Schema.Type<SchemaType>,
@@ -442,7 +473,7 @@ type ColumnModule<
 }
 
 /** Replaces a column's runtime schema while preserving its SQL type metadata. */
-export const schema = <SchemaType extends Schema.Schema.Any>(nextSchema: SchemaType) =>
+export const schema = <SchemaType extends Schema.Top>(nextSchema: SchemaType) =>
   <Column extends AnyColumnDefinition>(
     column: SchemaCompatibleColumn<Column, SchemaType>
   ): ColumnWithSchema<Column, SchemaType> =>
@@ -500,7 +531,7 @@ export const primaryKey = <Column extends AnyColumnDefinition>(
 type UniqueModifier = {
   <Column extends AnyColumnDefinition>(column: Column): UniqueColumn<Column>
   readonly options: <const Options extends ColumnUniqueOptions>(
-    options: Options
+    options: Options & NonEmptyOptionNameInput<Options>
   ) => <Column extends AnyColumnDefinition>(column: Column) => UniqueColumn<Column>
 }
 
@@ -550,11 +581,11 @@ export const generated = <Value extends DdlExpression>(value: Value) =>
     }) as GeneratedColumn<Column>
 
 /** Preserves the exact SQL type used for DDL rendering. */
-export const ddlType = <SqlType extends string>(sqlType: SqlType) =>
+export const ddlType = <SqlType extends string>(sqlType: NonEmptyStringInput<SqlType>) =>
   <Column extends AnyColumnDefinition>(column: Column): DdlTypedColumn<Column> =>
     mapColumn(column, {
       ...column.metadata,
-      ddlType: sqlType
+      ddlType: sqlType as SqlType
     }) as DdlTypedColumn<Column>
 
 /** Overrides how a column crosses the SQL driver boundary. */
@@ -590,13 +621,15 @@ export const array = <Options extends ArrayOptions | undefined = undefined>(
     }) as ArrayColumn<Column, Options>
 
 /** Marks a column as indexed. */
+type IndexPipe = <Column extends AnyColumnDefinition>(column: Column) => IndexedColumn<Column>
+
 export function index<Column extends AnyColumnDefinition>(
   column: Column
 ): IndexedColumn<Column>
 export function index<const Options extends ColumnIndexOptions>(
-  options: Options
+  options: Options & NonEmptyIndexMetadataInput<Options>
 ): <Column extends AnyColumnDefinition>(column: Column) => IndexedColumn<Column>
-export function index(arg: unknown): unknown {
+export function index(arg: AnyColumnDefinition | ColumnIndexOptions): IndexedColumn<AnyColumnDefinition> | IndexPipe {
   if (isColumnDefinitionValue(arg)) {
     return mapColumn(arg, {
       ...arg.metadata,
@@ -648,17 +681,21 @@ export const identityAlways = <Column extends AnyColumnDefinition>(
  *
  * The base, non-null select types must match.
  */
+type ForeignKeyPipe<Target extends AnyBoundColumn = AnyBoundColumn> = <Column extends AnyColumnDefinition>(
+  column: CompatibleReference<Column, Target>
+) => ReferencingColumn<Column, Target>
+
 export function foreignKey<Target extends AnyBoundColumn>(
   target: () => Target
 ): <Column extends AnyColumnDefinition>(
   column: CompatibleReference<Column, Target>
 ) => ReferencingColumn<Column, Target>
 export function foreignKey<const Options extends ForeignKeyOptions<AnyBoundColumn>>(
-  options: Options
+  options: Options & NonEmptyOptionNameInput<Options>
 ): <Column extends AnyColumnDefinition>(
   column: CompatibleReference<Column, ReturnType<Options["target"]>>
 ) => ReferencingColumn<Column, ReturnType<Options["target"]>>
-export function foreignKey(arg: unknown): unknown {
+export function foreignKey(arg: (() => AnyBoundColumn) | ForeignKeyOptions<AnyBoundColumn>): ForeignKeyPipe {
   if (typeof arg === "function") {
     const target = arg as () => AnyBoundColumn
     return <Column extends AnyColumnDefinition>(

package/src/internal/datatypes/define.ts

@@ -1,6 +1,11 @@
 import type * as Expression from "../scalar.js"
+import type { NonEmptyStringInput } from "../table-options.js"
 import type { DatatypeFamilySpec, DatatypeKindSpec } from "./shape.js"
 
+type ImplicitTargetsOf<Family> = Family extends { readonly implicitTargets: infer Targets extends readonly string[] }
+  ? Targets
+  : readonly []
+
 type DatatypeWitness<
   Dialect extends string,
   Kinds extends Record<string, DatatypeKindSpec>,
@@ -11,6 +16,7 @@ type DatatypeWitness<
   readonly runtime: Kinds[Kind]["runtime"]
   readonly compareGroup: Families[Kinds[Kind]["family"]]["compareGroup"]
   readonly castTargets: Families[Kinds[Kind]["family"]]["castTargets"]
+  readonly implicitTargets: ImplicitTargetsOf<Families[Kinds[Kind]["family"]]>
   readonly traits: Families[Kinds[Kind]["family"]]["traits"]
 }
 
@@ -20,7 +26,7 @@ export type DatatypeModule<
   Families extends Record<string, DatatypeFamilySpec>,
   Aliases extends Record<string, string> = Record<never, never>
 > = {
-  readonly custom: <Kind extends string>(kind: Kind) => Expression.DbType.Base<Dialect, Kind>
+  readonly custom: <Kind extends string>(kind: NonEmptyStringInput<Kind>) => Expression.DbType.Base<Dialect, Kind>
 } & {
   readonly [Kind in keyof Kinds]: () => DatatypeWitness<Dialect, Kinds, Families, Kind & string>
 } & {

package/src/internal/datatypes/enrich.ts

@@ -0,0 +1,23 @@
+import type * as Expression from "../scalar.js"
+
+type DatatypeLookup = Readonly<Record<string, (() => Expression.DbType.Any) | undefined>>
+
+export const enrichDbType = <
+  Module extends object,
+  Db extends Expression.DbType.Any
+>(
+  datatypes: Module,
+  dbType: Db
+): Db => {
+  if (dbType.kind === "custom") {
+    return dbType
+  }
+  const lookup = datatypes as DatatypeLookup
+  if (!(dbType.kind in lookup)) {
+    return dbType
+  }
+  const candidate = lookup[dbType.kind]
+  return typeof candidate === "function"
+    ? { ...candidate(), ...dbType } as Db
+    : dbType
+}