effect-qb 0.14.0 → 0.16.0

package/src/internal/scalar.d.ts

@@ -0,0 +1,107 @@
+import type { Pipeable } from "effect/Pipeable";
+import type * as Schema from "effect/Schema";
+import type { RuntimeOfDbType as RuntimeOfDbTypeLookup } from "./datatypes/lookup.js";
+import type { DatatypeTraits, RuntimeTag } from "./datatypes/shape.js";
+export type { BigIntString, DecimalString, InstantString, JsonPrimitive, JsonValue, LocalDateString, LocalDateTimeString, LocalTimeString, OffsetTimeString, YearString } from "./runtime/value.js";
+/** Symbol used to attach expression metadata to runtime values. */
+export declare const TypeId: unique symbol;
+export type TypeId = typeof TypeId;
+/** Scope-local binding identifier used for dependency tracking. */
+export type BindingId = string;
+/**
+ * Three-state nullability lattice.
+ *
+ * `"never"` means non-null, `"maybe"` means nullable, and `"always"` means the
+ * expression is known to be `null`.
+ */
+export type Nullability = "never" | "maybe" | "always";
+/**
+ * High-level classification of an expression.
+ *
+ * - `scalar`: regular per-row expression
+ * - `aggregate`: grouped expression such as `count(*)`
+ * - `window`: windowed expression such as `row_number() over (...)`
+ */
+export type ScalarKind = "scalar" | "aggregate" | "window";
+/** Database-type descriptors carried alongside decoded runtime types. */
+export declare namespace DbType {
+    /** Base SQL type descriptor. */
+    interface Base<Dialect extends string, Kind extends string> {
+        readonly dialect: Dialect;
+        readonly kind: Kind;
+        readonly family?: string;
+        readonly runtime?: RuntimeTag;
+        readonly compareGroup?: string;
+        readonly castTargets?: readonly string[];
+        readonly traits?: DatatypeTraits;
+    }
+    /** JSON-like database type. */
+    interface Json<Dialect extends string = string, SchemaName extends string = "json"> extends Base<Dialect, SchemaName> {
+        readonly variant: SchemaName extends "jsonb" ? "jsonb" : "json";
+    }
+    /** Array database type. */
+    interface Array<Dialect extends string = string, Element extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly element: Element;
+    }
+    /** Range database type. */
+    interface Range<Dialect extends string = string, Subtype extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly subtype: Subtype;
+    }
+    /** Multirange database type. */
+    interface Multirange<Dialect extends string = string, Subtype extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly subtype: Subtype;
+    }
+    /** Composite/record database type. */
+    interface Composite<Dialect extends string = string, Fields extends Record<string, Any> = Record<string, any>, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly fields: Fields;
+    }
+    /** Named domain database type. */
+    interface Domain<Dialect extends string = string, BaseType extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly base: BaseType;
+    }
+    /** Enumeration database type. */
+    interface Enum<Dialect extends string = string, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly variant: "enum";
+    }
+    /** Set database type. */
+    interface Set<Dialect extends string = string, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly variant: "set";
+    }
+    type Any = Json | Base<string, string> | Array<string, any, string> | Range<string, any, string> | Multirange<string, any, string> | Composite<string, Record<string, any>, string> | Domain<string, any, string> | Enum<string, string> | Set<string, string>;
+}
+/** Canonical static metadata stored on an expression. */
+export interface State<Runtime, Db extends DbType.Any, Nullable extends Nullability, Dialect extends string, Kind extends ScalarKind, Deps extends BindingId = never> {
+    readonly runtime: Runtime;
+    readonly dbType: Db;
+    readonly runtimeSchema?: Schema.Schema.Any;
+    readonly nullability: Nullable;
+    readonly dialect: Dialect;
+    readonly kind: Kind;
+    readonly dependencies: Record<string, true>;
+}
+/**
+ * A typed scalar SQL expression.
+ *
+ * `Runtime` is the decoded TypeScript type while `Db` captures the SQL-level
+ * type identity. Both are needed: multiple SQL types may decode to the same
+ * runtime type but still have different comparison/cast semantics.
+ */
+export interface Scalar<Runtime, Db extends DbType.Any, Nullable extends Nullability = "never", Dialect extends string = Db["dialect"], Kind extends ScalarKind = "scalar", Deps extends BindingId = never, GroupKey extends string = string> extends Pipeable {
+    readonly [TypeId]: State<Runtime, Db, Nullable, Dialect, Kind, Deps>;
+}
+/** Convenience alias for any expression-like value. */
+export type Any = Scalar<any, DbType.Any, Nullability, string, ScalarKind, BindingId, string>;
+/** Extracts an expression's decoded runtime type. */
+export type RuntimeOf<Value extends Any> = Value[typeof TypeId]["runtime"];
+/** Extracts an expression's database-type descriptor. */
+export type DbTypeOf<Value extends Any> = Value[typeof TypeId]["dbType"];
+/** Extracts an expression's nullability state. */
+export type NullabilityOf<Value extends Any> = Value[typeof TypeId]["nullability"];
+/** Extracts an expression's kind. */
+export type KindOf<Value extends Any> = Value[typeof TypeId]["kind"];
+/** Extracts an expression's source dependency union. */
+export type DependenciesOf<Value extends Any> = Value extends Scalar<any, any, any, any, any, infer Deps> ? Deps : never;
+/** Extracts an expression's grouping identity. */
+export type GroupKeyOf<Value extends Any> = Value extends Scalar<any, any, any, any, any, any, infer GroupKey> ? GroupKey : never;
+/** Maps a database type descriptor back to its decoded runtime type. */
+export type RuntimeOfDbType<Db extends DbType.Any> = RuntimeOfDbTypeLookup<Db>;

package/src/internal/scalar.ts

@@ -0,0 +1,202 @@
+import type { Pipeable } from "effect/Pipeable"
+import type * as Schema from "effect/Schema"
+import type { RuntimeOfDbType as RuntimeOfDbTypeLookup } from "./datatypes/lookup.js"
+import type { DatatypeTraits, RuntimeTag } from "./datatypes/shape.js"
+
+export type {
+  BigIntString,
+  DecimalString,
+  InstantString,
+  JsonPrimitive,
+  JsonValue,
+  LocalDateString,
+  LocalDateTimeString,
+  LocalTimeString,
+  OffsetTimeString,
+  YearString
+} from "./runtime/value.js"
+
+/** Symbol used to attach expression metadata to runtime values. */
+export const TypeId: unique symbol = Symbol.for("effect-qb/Expression")
+
+export type TypeId = typeof TypeId
+
+/** Scope-local binding identifier used for dependency tracking. */
+export type BindingId = string
+/**
+ * Three-state nullability lattice.
+ *
+ * `"never"` means non-null, `"maybe"` means nullable, and `"always"` means the
+ * expression is known to be `null`.
+ */
+export type Nullability = "never" | "maybe" | "always"
+
+/**
+ * High-level classification of an expression.
+ *
+ * - `scalar`: regular per-row expression
+ * - `aggregate`: grouped expression such as `count(*)`
+ * - `window`: windowed expression such as `row_number() over (...)`
+ */
+export type ScalarKind = "scalar" | "aggregate" | "window"
+
+/** Database-type descriptors carried alongside decoded runtime types. */
+export declare namespace DbType {
+  /** Base SQL type descriptor. */
+  export interface Base<Dialect extends string, Kind extends string> {
+    readonly dialect: Dialect
+    readonly kind: Kind
+    readonly family?: string
+    readonly runtime?: RuntimeTag
+    readonly compareGroup?: string
+    readonly castTargets?: readonly string[]
+    readonly traits?: DatatypeTraits
+    readonly driverValueMapping?: DriverValueMapping
+  }
+
+  /** JSON-like database type. */
+  export interface Json<
+    Dialect extends string = string,
+    SchemaName extends string = "json"
+  > extends Base<Dialect, SchemaName>
+  {
+    readonly variant: SchemaName extends "jsonb" ? "jsonb" : "json"
+  }
+
+  /** Array database type. */
+  export interface Array<
+    Dialect extends string = string,
+    Element extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly element: Element
+  }
+
+  /** Range database type. */
+  export interface Range<
+    Dialect extends string = string,
+    Subtype extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly subtype: Subtype
+  }
+
+  /** Multirange database type. */
+  export interface Multirange<
+    Dialect extends string = string,
+    Subtype extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly subtype: Subtype
+  }
+
+  /** Composite/record database type. */
+  export interface Composite<
+    Dialect extends string = string,
+    Fields extends Record<string, Any> = Record<string, any>,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly fields: Fields
+  }
+
+  /** Named domain database type. */
+  export interface Domain<
+    Dialect extends string = string,
+    BaseType extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly base: BaseType
+  }
+
+  /** Enumeration database type. */
+  export interface Enum<
+    Dialect extends string = string,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly variant: "enum"
+  }
+
+  /** Set database type. */
+  export interface Set<
+    Dialect extends string = string,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly variant: "set"
+  }
+
+  export type Any =
+    | Json
+    | Base<string, string>
+    | Array<string, any, string>
+    | Range<string, any, string>
+    | Multirange<string, any, string>
+    | Composite<string, Record<string, any>, string>
+    | Domain<string, any, string>
+    | Enum<string, string>
+    | Set<string, string>
+  }
+
+export interface DriverValueMapping {
+  readonly fromDriver?: (value: unknown, dbType: DbType.Any) => unknown
+  readonly toDriver?: (value: unknown, dbType: DbType.Any) => unknown
+  readonly selectSql?: (sql: string, dbType: DbType.Any) => string
+  readonly jsonSelectSql?: (sql: string, dbType: DbType.Any) => string
+}
+
+export type DriverValueMappings = Readonly<Record<string, DriverValueMapping | undefined>>
+
+/** Canonical static metadata stored on an expression. */
+export interface State<
+  Runtime,
+  Db extends DbType.Any,
+  Nullable extends Nullability,
+  Dialect extends string,
+  Kind extends ScalarKind,
+  Deps extends BindingId = never
+> {
+  readonly runtime: Runtime
+  readonly dbType: Db
+  readonly runtimeSchema?: Schema.Schema.Any
+  readonly driverValueMapping?: DriverValueMapping
+  readonly nullability: Nullable
+  readonly dialect: Dialect
+  readonly kind: Kind
+  readonly dependencies: Record<string, true>
+}
+
+/**
+ * A typed scalar SQL expression.
+ *
+ * `Runtime` is the decoded TypeScript type while `Db` captures the SQL-level
+ * type identity. Both are needed: multiple SQL types may decode to the same
+ * runtime type but still have different comparison/cast semantics.
+ */
+export interface Scalar<
+  Runtime,
+  Db extends DbType.Any,
+  Nullable extends Nullability = "never",
+  Dialect extends string = Db["dialect"],
+  Kind extends ScalarKind = "scalar",
+  Deps extends BindingId = never,
+  GroupKey extends string = string
+> extends Pipeable {
+  readonly [TypeId]: State<Runtime, Db, Nullable, Dialect, Kind, Deps>
+}
+
+/** Convenience alias for any expression-like value. */
+export type Any = Scalar<any, DbType.Any, Nullability, string, ScalarKind, BindingId, string>
+/** Extracts an expression's decoded runtime type. */
+export type RuntimeOf<Value extends Any> = Value[typeof TypeId]["runtime"]
+/** Extracts an expression's database-type descriptor. */
+export type DbTypeOf<Value extends Any> = Value[typeof TypeId]["dbType"]
+/** Extracts an expression's nullability state. */
+export type NullabilityOf<Value extends Any> = Value[typeof TypeId]["nullability"]
+/** Extracts an expression's kind. */
+export type KindOf<Value extends Any> = Value[typeof TypeId]["kind"]
+/** Extracts an expression's source dependency union. */
+export type DependenciesOf<Value extends Any> = Value extends Scalar<any, any, any, any, any, infer Deps> ? Deps : never
+/** Extracts an expression's grouping identity. */
+export type GroupKeyOf<Value extends Any> = Value extends Scalar<any, any, any, any, any, any, infer GroupKey> ? GroupKey : never
+
+/** Maps a database type descriptor back to its decoded runtime type. */
+export type RuntimeOfDbType<Db extends DbType.Any> = RuntimeOfDbTypeLookup<Db>

package/src/internal/schema-derivation.d.ts

@@ -0,0 +1,105 @@
+import * as VariantSchema from "@effect/experimental/VariantSchema";
+import type * as Brand from "effect/Brand";
+import * as Schema from "effect/Schema";
+import { type AnyColumnDefinition, type HasDefault, type InsertType, type IsGenerated, type IsNullable, type SelectType, type UpdateType } from "./column-state.js";
+/** Variant-schema helper used to derive select / insert / update schemas. */
+export declare const TableSchema: {
+    readonly Struct: <const A extends VariantSchema.Struct.Fields>(fields: A & VariantSchema.Struct.Validate<A, "insert" | "select" | "update">) => VariantSchema.Struct<A>;
+    readonly Field: <const A extends VariantSchema.Field.ConfigWithKeys<"insert" | "select" | "update">>(config: A & { readonly [K in Exclude<keyof A, "insert" | "select" | "update">]: never; }) => VariantSchema.Field<A>;
+    readonly FieldOnly: <const Keys extends readonly ("insert" | "select" | "update")[]>(...keys: Keys) => <S extends Schema.Schema.All | Schema.PropertySignature.All<PropertyKey>>(schema: S) => VariantSchema.Field<{ readonly [K in Keys[number]]: S; }>;
+    readonly FieldExcept: <const Keys extends readonly ("insert" | "select" | "update")[]>(...keys: Keys) => <S extends Schema.Schema.All | Schema.PropertySignature.All<PropertyKey>>(schema: S) => VariantSchema.Field<{ readonly [K in Exclude<"insert", Keys[number]> | Exclude<"select", Keys[number]> | Exclude<"update", Keys[number]>]: S; }>;
+    readonly fieldEvolve: {
+        <Self extends VariantSchema.Field<any> | VariantSchema.Field.ValueAny, const Mapping extends Self extends VariantSchema.Field<infer S extends VariantSchema.Field.Config> ? { readonly [K in keyof S]?: ((variant: S[K]) => VariantSchema.Field.ValueAny) | undefined; } : {
+            readonly insert?: ((variant: Self) => VariantSchema.Field.ValueAny) | undefined;
+            readonly select?: ((variant: Self) => VariantSchema.Field.ValueAny) | undefined;
+            readonly update?: ((variant: Self) => VariantSchema.Field.ValueAny) | undefined;
+        }>(f: Mapping): (self: Self) => VariantSchema.Field<Self extends VariantSchema.Field<infer S_1 extends VariantSchema.Field.Config> ? { readonly [K in keyof S_1]: K extends keyof Mapping ? Mapping[K] extends (arg: any) => any ? ReturnType<Mapping[K]> : S_1[K] : S_1[K]; } : {
+            readonly insert: "insert" extends infer T ? T extends "insert" ? T extends keyof Mapping ? Mapping[T] extends (arg: any) => any ? ReturnType<Mapping[T]> : Self : Self : never : never;
+            readonly select: "select" extends infer T_1 ? T_1 extends "select" ? T_1 extends keyof Mapping ? Mapping[T_1] extends (arg: any) => any ? ReturnType<Mapping[T_1]> : Self : Self : never : never;
+            readonly update: "update" extends infer T_2 ? T_2 extends "update" ? T_2 extends keyof Mapping ? Mapping[T_2] extends (arg: any) => any ? ReturnType<Mapping[T_2]> : Self : Self : never : never;
+        }>;
+        <Self extends VariantSchema.Field<any> | VariantSchema.Field.ValueAny, const Mapping_1 extends Self extends VariantSchema.Field<infer S extends VariantSchema.Field.Config> ? { readonly [K in keyof S]?: ((variant: S[K]) => VariantSchema.Field.ValueAny) | undefined; } : {
+            readonly insert?: ((variant: Self) => VariantSchema.Field.ValueAny) | undefined;
+            readonly select?: ((variant: Self) => VariantSchema.Field.ValueAny) | undefined;
+            readonly update?: ((variant: Self) => VariantSchema.Field.ValueAny) | undefined;
+        }>(self: Self, f: Mapping_1): VariantSchema.Field<Self extends VariantSchema.Field<infer S_1 extends VariantSchema.Field.Config> ? { readonly [K in keyof S_1]: K extends keyof Mapping_1 ? Mapping_1[K] extends (arg: any) => any ? ReturnType<Mapping_1[K]> : S_1[K] : S_1[K]; } : {
+            readonly insert: "insert" extends infer T ? T extends "insert" ? T extends keyof Mapping_1 ? Mapping_1[T] extends (arg: any) => any ? ReturnType<Mapping_1[T]> : Self : Self : never : never;
+            readonly select: "select" extends infer T_1 ? T_1 extends "select" ? T_1 extends keyof Mapping_1 ? Mapping_1[T_1] extends (arg: any) => any ? ReturnType<Mapping_1[T_1]> : Self : Self : never : never;
+            readonly update: "update" extends infer T_2 ? T_2 extends "update" ? T_2 extends keyof Mapping_1 ? Mapping_1[T_2] extends (arg: any) => any ? ReturnType<Mapping_1[T_2]> : Self : Self : never : never;
+        }>;
+    };
+    readonly fieldFromKey: {
+        <Self extends VariantSchema.Field<any> | VariantSchema.Field.ValueAny, const Mapping_2 extends Self extends VariantSchema.Field<infer S extends VariantSchema.Field.Config> ? { readonly [K in keyof S]?: string | undefined; } : {
+            readonly insert?: string | undefined;
+            readonly select?: string | undefined;
+            readonly update?: string | undefined;
+        }>(mapping: Mapping_2): (self: Self) => VariantSchema.Field<Self extends VariantSchema.Field<infer S_1 extends VariantSchema.Field.Config> ? { readonly [K in keyof S_1]: K extends keyof Mapping_2 ? Mapping_2[K] extends string ? VariantSchema.fromKey.Rename<S_1[K], Mapping_2[K]> : S_1[K] : S_1[K]; } : {
+            readonly insert: "insert" extends infer T ? T extends "insert" ? T extends keyof Mapping_2 ? Mapping_2[T] extends string ? VariantSchema.fromKey.Rename<Self, Mapping_2[T]> : Self : Self : never : never;
+            readonly select: "select" extends infer T_1 ? T_1 extends "select" ? T_1 extends keyof Mapping_2 ? Mapping_2[T_1] extends string ? VariantSchema.fromKey.Rename<Self, Mapping_2[T_1]> : Self : Self : never : never;
+            readonly update: "update" extends infer T_2 ? T_2 extends "update" ? T_2 extends keyof Mapping_2 ? Mapping_2[T_2] extends string ? VariantSchema.fromKey.Rename<Self, Mapping_2[T_2]> : Self : Self : never : never;
+        }>;
+        <Self extends VariantSchema.Field<any> | VariantSchema.Field.ValueAny, const Mapping_3 extends Self extends VariantSchema.Field<infer S extends VariantSchema.Field.Config> ? { readonly [K in keyof S]?: string | undefined; } : {
+            readonly insert?: string | undefined;
+            readonly select?: string | undefined;
+            readonly update?: string | undefined;
+        }>(self: Self, mapping: Mapping_3): VariantSchema.Field<Self extends VariantSchema.Field<infer S_1 extends VariantSchema.Field.Config> ? { readonly [K in keyof S_1]: K extends keyof Mapping_3 ? Mapping_3[K] extends string ? VariantSchema.fromKey.Rename<S_1[K], Mapping_3[K]> : S_1[K] : S_1[K]; } : {
+            readonly insert: "insert" extends infer T ? T extends "insert" ? T extends keyof Mapping_3 ? Mapping_3[T] extends string ? VariantSchema.fromKey.Rename<Self, Mapping_3[T]> : Self : Self : never : never;
+            readonly select: "select" extends infer T_1 ? T_1 extends "select" ? T_1 extends keyof Mapping_3 ? Mapping_3[T_1] extends string ? VariantSchema.fromKey.Rename<Self, Mapping_3[T_1]> : Self : Self : never : never;
+            readonly update: "update" extends infer T_2 ? T_2 extends "update" ? T_2 extends keyof Mapping_3 ? Mapping_3[T_2] extends string ? VariantSchema.fromKey.Rename<Self, Mapping_3[T_2]> : Self : Self : never : never;
+        }>;
+    };
+    readonly Class: <Self = never>(identifier: string) => <const Fields extends VariantSchema.Struct.Fields>(fields: Fields & VariantSchema.Struct.Validate<Fields, "insert" | "select" | "update">, annotations?: Schema.Annotations.Schema<Self, readonly []> | undefined) => [Self] extends [never] ? "Missing `Self` generic - use `class Self extends Class<Self>()({ ... })`" : VariantSchema.Class<Self, Fields, VariantSchema.ExtractFields<"select", Fields, true>, Schema.Struct.Type<VariantSchema.ExtractFields<"select", Fields, true>>, Schema.Struct.Encoded<VariantSchema.ExtractFields<"select", Fields, true>>, Schema.Schema.Context<VariantSchema.ExtractFields<"select", Fields, true>[keyof VariantSchema.ExtractFields<"select", Fields, true>]>, Schema.Struct.Constructor<VariantSchema.ExtractFields<"select", Fields, true>>> & {
+        readonly insert: Schema.Struct<VariantSchema.ExtractFields<"insert", Fields, false> extends infer T ? { [K in keyof T]: T[K]; } : never>;
+        readonly select: Schema.Struct<VariantSchema.ExtractFields<"select", Fields, false> extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never>;
+        readonly update: Schema.Struct<VariantSchema.ExtractFields<"update", Fields, false> extends infer T_2 ? { [K in keyof T_2]: T_2[K]; } : never>;
+    };
+    readonly Union: <const Members extends readonly VariantSchema.Struct<any>[]>(...members: Members) => VariantSchema.Union<Members> & VariantSchema.Union.Variants<Members, "insert" | "select" | "update">;
+    readonly extract: {
+        <V extends "insert" | "select" | "update">(variant: V): <A extends VariantSchema.Struct<any>>(self: A) => VariantSchema.Extract<V, A, V extends "select" ? true : false>;
+        <V extends "insert" | "select" | "update", A extends VariantSchema.Struct<any>>(self: A, variant: V): VariantSchema.Extract<V, A, V extends "select" ? true : false>;
+    };
+};
+/** Normalized field map used by table definitions. */
+export type TableFieldMap = Record<string, AnyColumnDefinition>;
+type GeneratedKeys<Fields extends TableFieldMap> = {
+    [K in keyof Fields]: IsGenerated<Fields[K]> extends true ? K : never;
+}[keyof Fields];
+type OptionalInsertKeys<Fields extends TableFieldMap> = {
+    [K in keyof Fields]: IsGenerated<Fields[K]> extends true ? never : IsNullable<Fields[K]> extends true ? K : HasDefault<Fields[K]> extends true ? K : never;
+}[keyof Fields];
+type RequiredInsertKeys<Fields extends TableFieldMap> = Exclude<keyof Fields, GeneratedKeys<Fields> | OptionalInsertKeys<Fields>>;
+type UpdateKeys<Fields extends TableFieldMap, PrimaryKey extends keyof Fields> = Exclude<keyof Fields, GeneratedKeys<Fields> | PrimaryKey>;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type BrandedValue<Value, BrandName extends string> = [Extract<Value, null | undefined>] extends [never] ? Value & Brand.Brand<BrandName> : (Exclude<Value, null | undefined> & Brand.Brand<BrandName>) | Extract<Value, null | undefined>;
+type BrandNameOf<TableName extends string, ColumnName extends string> = `${TableName}.${ColumnName}`;
+type BrandedSelectType<Column extends AnyColumnDefinition, TableName extends string, ColumnName extends string> = Column["metadata"]["brand"] extends true ? BrandedValue<SelectType<Column>, BrandNameOf<TableName, ColumnName>> : SelectType<Column>;
+type BrandedInsertType<Column extends AnyColumnDefinition, TableName extends string, ColumnName extends string> = Column["metadata"]["brand"] extends true ? BrandedValue<InsertType<Column>, BrandNameOf<TableName, ColumnName>> : InsertType<Column>;
+type BrandedUpdateType<Column extends AnyColumnDefinition, TableName extends string, ColumnName extends string> = Column["metadata"]["brand"] extends true ? BrandedValue<UpdateType<Column>, BrandNameOf<TableName, ColumnName>> : UpdateType<Column>;
+/** Row shape returned by selecting from a table. */
+export type SelectRow<TableName extends string, Fields extends TableFieldMap> = Simplify<{
+    [K in keyof Fields]: BrandedSelectType<Fields[K], TableName, Extract<K, string>>;
+}>;
+/** Insert payload derived from a table field map. */
+export type InsertRow<TableName extends string, Fields extends TableFieldMap> = Simplify<{
+    [K in RequiredInsertKeys<Fields>]: BrandedInsertType<Fields[K], TableName, Extract<K, string>>;
+} & {
+    [K in OptionalInsertKeys<Fields>]?: BrandedInsertType<Fields[K], TableName, Extract<K, string>>;
+}>;
+/** Update payload derived from a table field map and primary key. */
+export type UpdateRow<TableName extends string, Fields extends TableFieldMap, PrimaryKey extends keyof Fields> = Simplify<Partial<{
+    [K in UpdateKeys<Fields, PrimaryKey>]: BrandedUpdateType<Fields[K], TableName, Extract<K, string>>;
+}>>;
+/**
+ * Derives the `select`, `insert`, and `update` schemas for a table.
+ *
+ * This is the central place where the column capability flags are turned into
+ * real runtime schemas.
+ */
+export declare const deriveSchemas: <TableName extends string, Fields extends TableFieldMap, PrimaryKeyColumns extends keyof Fields & string>(tableName: TableName, fields: Fields, primaryKeyColumns: readonly PrimaryKeyColumns[]) => {
+    readonly select: Schema.Schema<{ [K in keyof { [K in keyof Fields]: BrandedSelectType<Fields[K], TableName, Extract<K, string>>; }]: { [K in keyof Fields]: BrandedSelectType<Fields[K], TableName, Extract<K, string>>; }[K]; }, { [K in keyof { [K in keyof Fields]: BrandedSelectType<Fields[K], TableName, Extract<K, string>>; }]: { [K in keyof Fields]: BrandedSelectType<Fields[K], TableName, Extract<K, string>>; }[K]; }, never>;
+    readonly insert: Schema.Schema<{ [K in Exclude<keyof Fields, GeneratedKeys<Fields> | OptionalInsertKeys<Fields>>]: BrandedInsertType<Fields[K], TableName, Extract<K, string>>; } & { [K in OptionalInsertKeys<Fields>]?: BrandedInsertType<Fields[K], TableName, Extract<K, string>> | undefined; } extends infer T ? { [K in keyof T]: T[K]; } : never, { [K in Exclude<keyof Fields, GeneratedKeys<Fields> | OptionalInsertKeys<Fields>>]: BrandedInsertType<Fields[K], TableName, Extract<K, string>>; } & { [K in OptionalInsertKeys<Fields>]?: BrandedInsertType<Fields[K], TableName, Extract<K, string>> | undefined; } extends infer T ? { [K in keyof T]: T[K]; } : never, never>;
+    readonly update: Schema.Schema<Partial<{ [K in Exclude<keyof Fields, PrimaryKeyColumns | GeneratedKeys<Fields>>]: BrandedUpdateType<Fields[K], TableName, Extract<K, string>>; }> extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never, Partial<{ [K in Exclude<keyof Fields, PrimaryKeyColumns | GeneratedKeys<Fields>>]: BrandedUpdateType<Fields[K], TableName, Extract<K, string>>; }> extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never, never>;
+};
+export {};

package/src/internal/schema-expression.d.ts

@@ -0,0 +1,18 @@
+import { type Expr } from "pgsql-ast-parser";
+import { type Pipeable } from "effect/Pipeable";
+export declare const TypeId: unique symbol;
+export type TypeId = typeof TypeId;
+export interface SchemaExpression extends Pipeable {
+    readonly [TypeId]: {
+        readonly ast?: Expr;
+        readonly sql?: string;
+    };
+}
+export type Any = SchemaExpression;
+export declare const isSchemaExpression: (value: unknown) => value is SchemaExpression;
+export declare const fromAst: (ast: Expr) => SchemaExpression;
+export declare const fromSql: (sql: string) => SchemaExpression;
+export declare const parseExpression: (sql: string) => SchemaExpression;
+export declare const toAst: (expression: SchemaExpression) => Expr;
+export declare const render: (expression: SchemaExpression) => string;
+export declare const normalize: (expression: SchemaExpression) => SchemaExpression;

package/src/internal/schema-expression.ts

@@ -11,10 +11,21 @@ const SchemaExpressionProto = {
   }
 }
 
+const attachPipe = <Value extends object>(value: Value): Value => {
+  Object.defineProperty(value, "pipe", {
+    configurable: true,
+    writable: true,
+    value: function(this: unknown) {
+      return pipeArguments(value, arguments)
+    }
+  })
+  return value
+}
+
 export interface SchemaExpression extends Pipeable {
   readonly [TypeId]: {
-    readonly dialect: "postgres"
-    readonly ast: Expr
+    readonly ast?: Expr
+    readonly sql?: string
   }
 }
 
@@ -24,21 +35,41 @@ export const isSchemaExpression = (value: unknown): value is SchemaExpression =>
   typeof value === "object" && value !== null && TypeId in value
 
 export const fromAst = (ast: Expr): SchemaExpression => {
-  const expression = Object.create(SchemaExpressionProto)
+  const expression = attachPipe(Object.create(SchemaExpressionProto))
   expression[TypeId] = {
-    dialect: "postgres",
     ast
   }
   return expression
 }
 
+export const fromSql = (sql: string): SchemaExpression => {
+  const expression = attachPipe(Object.create(SchemaExpressionProto))
+  expression[TypeId] = {
+    sql: sql.trim()
+  }
+  return expression
+}
+
 export const parseExpression = (sql: string): SchemaExpression =>
   fromAst(parse(sql, "expr"))
 
-export const toAst = (expression: SchemaExpression): Expr => expression[TypeId].ast
+export const toAst = (expression: SchemaExpression): Expr => {
+  const ast = expression[TypeId].ast
+  if (ast !== undefined) {
+    return ast
+  }
+  return parse(render(expression), "expr")
+}
 
 export const render = (expression: SchemaExpression): string =>
-  toSql.expr(expression[TypeId].ast)
+  expression[TypeId].sql ?? toSql.expr(toAst(expression))
 
 export const normalize = (expression: SchemaExpression): SchemaExpression =>
-  parseExpression(render(expression))
+  (() => {
+    const sql = render(expression)
+    try {
+      return parseExpression(sql)
+    } catch {
+      return fromSql(sql)
+    }
+  })()

package/src/internal/table-options.d.ts

@@ -0,0 +1,94 @@
+import { type AnyColumnDefinition, type IsNullable } from "./column-state.js";
+import type { Any as AnyExpression } from "./scalar.js";
+import type { Any as AnySchemaExpression } from "./schema-expression.js";
+import type { TableFieldMap } from "./schema-derivation.js";
+/** Non-empty list of column names. */
+export type ColumnList = readonly [string, ...string[]];
+export type DdlExpressionLike = AnyExpression | AnySchemaExpression;
+export type ReferentialAction = "noAction" | "restrict" | "cascade" | "setNull" | "setDefault";
+export type IndexKeySpec = {
+    readonly kind: "column";
+    readonly column: string;
+    readonly order?: "asc" | "desc";
+    readonly nulls?: "first" | "last";
+    readonly operatorClass?: string;
+    readonly collation?: string;
+} | {
+    readonly kind: "expression";
+    readonly expression: DdlExpressionLike;
+    readonly order?: "asc" | "desc";
+    readonly nulls?: "first" | "last";
+    readonly operatorClass?: string;
+    readonly collation?: string;
+};
+/** Normalized table-level option record. */
+export type TableOptionSpec = {
+    readonly kind: "index";
+    readonly columns?: ColumnList;
+    readonly name?: string;
+    readonly unique?: boolean;
+    readonly method?: string;
+    readonly include?: readonly string[];
+    readonly predicate?: DdlExpressionLike;
+    readonly keys?: readonly [IndexKeySpec, ...IndexKeySpec[]];
+} | {
+    readonly kind: "unique";
+    readonly columns: ColumnList;
+    readonly name?: string;
+    readonly nullsNotDistinct?: boolean;
+    readonly deferrable?: boolean;
+    readonly initiallyDeferred?: boolean;
+} | {
+    readonly kind: "primaryKey";
+    readonly columns: ColumnList;
+    readonly name?: string;
+    readonly deferrable?: boolean;
+    readonly initiallyDeferred?: boolean;
+} | {
+    readonly kind: "foreignKey";
+    readonly columns: ColumnList;
+    readonly name?: string;
+    readonly references: () => {
+        readonly tableName: string;
+        readonly schemaName?: string;
+        readonly columns: ColumnList;
+        readonly knownColumns?: readonly string[];
+    };
+    readonly onUpdate?: ReferentialAction;
+    readonly onDelete?: ReferentialAction;
+    readonly deferrable?: boolean;
+    readonly initiallyDeferred?: boolean;
+} | {
+    readonly kind: "check";
+    readonly name: string;
+    readonly predicate: DdlExpressionLike;
+    readonly noInherit?: boolean;
+};
+/** Thin wrapper used by the public `Table.*` option builders. */
+export interface TableOptionBuilder<Spec extends TableOptionSpec = TableOptionSpec> {
+    readonly option: Spec;
+}
+/** Collection of declared table options. */
+export type DeclaredTableOptions = readonly TableOptionBuilder[];
+type ColumnNameUnion<Fields extends TableFieldMap> = Extract<keyof Fields, string>;
+type NullableColumnNames<Fields extends TableFieldMap> = {
+    [K in keyof Fields]: Fields[K] extends AnyColumnDefinition ? IsNullable<Fields[K]> extends true ? K : never : never;
+}[keyof Fields];
+type TupleFromColumns<Columns> = Columns extends readonly [infer Head extends string, ...infer Tail extends string[]] ? readonly [Head, ...Tail] : Columns extends readonly string[] ? Columns extends readonly [string, ...string[]] ? Columns : never : Columns extends string ? readonly [Columns] : never;
+type AssertKnownColumns<Fields extends TableFieldMap, Columns extends readonly string[]> = Exclude<Columns[number], ColumnNameUnion<Fields>> extends never ? Columns : never;
+type AssertPrimaryKeyColumns<Fields extends TableFieldMap, Columns extends readonly string[]> = Extract<Columns[number], NullableColumnNames<Fields>> extends never ? Columns : never;
+/** Normalizes a string or tuple input into a non-empty column list. */
+export declare const normalizeColumnList: (columns: string | readonly string[]) => ColumnList;
+/** Converts inline column flags into normalized table option records. */
+export declare const collectInlineOptions: <Fields extends TableFieldMap>(fields: Fields) => readonly TableOptionSpec[];
+/** Resolves the effective primary-key columns for a table. */
+export declare const resolvePrimaryKeyColumns: <Fields extends TableFieldMap>(fields: Fields, declaredOptions: readonly TableOptionSpec[]) => readonly (keyof Fields & string)[];
+/** Validates that options reference known, legal columns for the table. */
+export declare const validateOptions: <Fields extends TableFieldMap>(tableName: string, fields: Fields, options: readonly TableOptionSpec[]) => void;
+/** Compile-time validation that option columns exist on the table. */
+export type ValidateKnownColumns<Fields extends TableFieldMap, Columns extends readonly string[]> = AssertKnownColumns<Fields, Columns>;
+/** Compile-time validation that primary-key columns are known and non-nullable. */
+export type ValidatePrimaryKeyColumns<Fields extends TableFieldMap, Columns extends readonly string[]> = AssertPrimaryKeyColumns<Fields, AssertKnownColumns<Fields, Columns>>;
+/** Normalizes a public column input into the internal tuple form. */
+export type NormalizeColumns<Columns extends string | readonly string[]> = TupleFromColumns<Columns>;
+export {};

package/src/internal/table-options.ts

@@ -4,7 +4,7 @@ import {
   type AnyColumnDefinition,
   type IsNullable
 } from "./column-state.js"
-import type { Any as AnyExpression } from "./expression.js"
+import type { Any as AnyExpression } from "./scalar.js"
 import type { Any as AnySchemaExpression } from "./schema-expression.js"
 import type { TableFieldMap } from "./schema-derivation.js"
 
@@ -21,12 +21,16 @@ export type IndexKeySpec =
       readonly column: string
       readonly order?: "asc" | "desc"
       readonly nulls?: "first" | "last"
+      readonly operatorClass?: string
+      readonly collation?: string
     }
   | {
       readonly kind: "expression"
       readonly expression: DdlExpressionLike
       readonly order?: "asc" | "desc"
       readonly nulls?: "first" | "last"
+      readonly operatorClass?: string
+      readonly collation?: string
     }
 
 /** Normalized table-level option record. */
@@ -182,7 +186,9 @@ export const collectInlineOptions = <Fields extends TableFieldMap>(
           kind: "column",
           column: columnName,
           order: column.metadata.index.order,
-          nulls: column.metadata.index.nulls
+          nulls: column.metadata.index.nulls,
+          operatorClass: column.metadata.index.operatorClass,
+          collation: column.metadata.index.collation
         }],
         name: column.metadata.index.name,
         method: column.metadata.index.method,