effect-qb 0.13.0 → 0.15.0

package/src/postgres/table.ts

@@ -1,6 +1,6 @@
 import type * as Schema from "effect/Schema"
 
-import type * as Expression from "../internal/expression.js"
+import type * as Expression from "../internal/scalar.js"
 import { ColumnTypeId, type AnyColumnDefinition } from "../internal/column-state.js"
 import * as BaseTable from "../internal/table.js"
 
@@ -53,20 +53,26 @@ type SchemaNameOfTable<Table> = Table extends BaseTable.TableDefinition<any, any
     ? SchemaName
     : never
 
-export type TableSchemaNamespace<SchemaName extends string> = {
-  readonly schemaName: SchemaName
-  readonly table: <
-    Name extends string,
-    Fields extends DialectFieldMap,
-    PrimaryKeyColumns extends keyof Fields & string = InlinePrimaryKeyKeys<Fields>
-  >(
-    name: Name,
-    fields: Fields,
-    ...options: BaseTable.DeclaredTableOptions
-  ) => TableDefinition<Name, Fields, PrimaryKeyColumns, "schema", SchemaName>
+export type TableOption = BaseTable.TableOption
+export type DdlExpressionLike = BaseTable.DdlExpressionLike
+export type IndexKey = BaseTable.IndexKeySpec
+export type ReferentialAction = BaseTable.ReferentialAction
+
+type SchemaTable = {
+  readonly columns: Record<string, unknown>
 }
 
-export type TableOption = BaseTable.TableOption
+type TableExpressionFactory<Table extends SchemaTable> = (
+  columns: Table["columns"]
+) => DdlExpressionLike
+
+type TableScopedOptionBuilder<
+  Table extends SchemaTable,
+  Spec extends import("../internal/table-options.js").TableOptionSpec = import("../internal/table-options.js").TableOptionSpec
+> = {
+  (table: Table): Table
+  readonly option: Spec
+}
 
 export const TypeId = BaseTable.TypeId
 export const OptionsSymbol = BaseTable.OptionsSymbol
@@ -83,26 +89,6 @@ export const make = <
 ): TableDefinition<Name, Fields> =>
   BaseTable.make(name, fields, schemaName) as TableDefinition<Name, Fields>
 
-export const schema = <SchemaName extends string>(
-  schemaName: SchemaName
-): TableSchemaNamespace<SchemaName> => ({
-  schemaName,
-  table: <
-    Name extends string,
-    Fields extends DialectFieldMap,
-    PrimaryKeyColumns extends keyof Fields & string = InlinePrimaryKeyKeys<Fields>
-  >(
-    name: Name,
-    fields: Fields,
-    ...declaredOptions: BaseTable.DeclaredTableOptions
-  ) =>
-    BaseTable.schema(schemaName).table(
-      name,
-      fields,
-      ...declaredOptions
-    ) as TableDefinition<Name, Fields, PrimaryKeyColumns, "schema", SchemaName>
-})
-
 export const alias = <
   Table extends AnyTable,
   AliasName extends string
@@ -136,21 +122,309 @@ export const Class = <Self = never, SchemaName extends string | undefined = "pub
     : TableClassStatic<typeof name, Fields, InlinePrimaryKeyKeys<Fields>, SchemaName>
 }
 
-export const primaryKey = BaseTable.primaryKey
-export const unique = BaseTable.unique
-export const index = BaseTable.index
-export const foreignKey = <
+export const option = BaseTable.option
+
+type RichPrimaryKeyInput<Columns extends string | readonly string[]> = {
+  readonly columns: Columns
+  readonly name?: string
+  readonly deferrable?: boolean
+  readonly initiallyDeferred?: boolean
+}
+
+type RichUniqueInput<Columns extends string | readonly string[]> = {
+  readonly columns: Columns
+  readonly name?: string
+  readonly nullsNotDistinct?: boolean
+  readonly deferrable?: boolean
+  readonly initiallyDeferred?: boolean
+}
+
+type RichIndexKeyInput =
+  | {
+      readonly column: string
+      readonly order?: "asc" | "desc"
+      readonly nulls?: "first" | "last"
+      readonly operatorClass?: string
+      readonly collation?: string
+    }
+  | {
+      readonly expression: DdlExpressionLike
+      readonly order?: "asc" | "desc"
+      readonly nulls?: "first" | "last"
+      readonly operatorClass?: string
+      readonly collation?: string
+    }
+
+type RichIndexInput<Columns extends string | readonly string[] = string | readonly string[]> = {
+  readonly columns?: Columns
+  readonly keys?: readonly [RichIndexKeyInput, ...RichIndexKeyInput[]]
+  readonly name?: string
+  readonly unique?: boolean
+  readonly method?: string
+  readonly include?: readonly string[]
+  readonly predicate?: DdlExpressionLike
+}
+
+type RichForeignKeyInput<
   LocalColumns extends string | readonly string[],
   TargetTable extends AnyTable,
   TargetColumns extends string | readonly string[]
+> = {
+  readonly columns: LocalColumns
+  readonly target: () => TargetTable
+  readonly referencedColumns: TargetColumns
+  readonly name?: string
+  readonly onUpdate?: ReferentialAction
+  readonly onDelete?: ReferentialAction
+  readonly deferrable?: boolean
+  readonly initiallyDeferred?: boolean
+}
+
+type RichCheckInput<Name extends string = string> = {
+  readonly name: Name
+  readonly predicate: DdlExpressionLike
+  readonly noInherit?: boolean
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const isTableExpressionFactory = (value: unknown): value is TableExpressionFactory<SchemaTable> =>
+  typeof value === "function"
+
+const makeTableScopedOption = <
+  Table extends SchemaTable,
+  Spec extends import("../internal/table-options.js").TableOptionSpec
+>(
+  placeholder: Spec,
+  resolve: (table: Table) => Spec
+): TableScopedOptionBuilder<Table, Spec> => {
+  const builder = ((table: Table) =>
+    BaseTable.option(resolve(table))(table as never)) as unknown as TableScopedOptionBuilder<Table, Spec>
+  ;(builder as { option: Spec }).option = placeholder
+  return builder
+}
+
+const normalizeColumns = (columns: string | readonly string[]): readonly [string, ...string[]] =>
+  (Array.isArray(columns) ? [...columns] : [columns]) as unknown as readonly [string, ...string[]]
+
+const normalizeIndexKeys = (
+  keys: readonly [RichIndexKeyInput, ...RichIndexKeyInput[]]
+): readonly [BaseTable.IndexKeySpec, ...BaseTable.IndexKeySpec[]] =>
+  keys.map((key) => "expression" in key
+      ? {
+        kind: "expression",
+        expression: key.expression,
+        order: key.order,
+        nulls: key.nulls,
+        operatorClass: key.operatorClass,
+        collation: key.collation
+      }
+    : {
+        kind: "column",
+        column: key.column,
+        order: key.order,
+        nulls: key.nulls,
+        operatorClass: key.operatorClass,
+        collation: key.collation
+      }) as unknown as readonly [BaseTable.IndexKeySpec, ...BaseTable.IndexKeySpec[]]
+
+export const primaryKey: {
+  <const Columns extends string | readonly string[]>(
+    columns: Columns
+  ): BaseTable.TableOption<{
+    readonly kind: "primaryKey"
+    readonly columns: BaseTable.NormalizeColumns<Columns>
+  }>
+  <const Columns extends string | readonly string[]>(
+    spec: RichPrimaryKeyInput<Columns>
+  ): BaseTable.TableOption
+} = ((input: unknown) =>
+  isObject(input) && "columns" in input
+    ? BaseTable.option({
+        kind: "primaryKey",
+        columns: normalizeColumns((input as RichPrimaryKeyInput<string | readonly string[]>).columns),
+        name: (input as RichPrimaryKeyInput<string | readonly string[]>).name,
+        deferrable: (input as RichPrimaryKeyInput<string | readonly string[]>).deferrable,
+        initiallyDeferred: (input as RichPrimaryKeyInput<string | readonly string[]>).initiallyDeferred
+      })
+    : BaseTable.primaryKey(input as string | readonly string[])) as never
+
+export const unique: {
+  <const Columns extends string | readonly string[]>(
+    columns: Columns
+  ): BaseTable.TableOption<{
+    readonly kind: "unique"
+    readonly columns: BaseTable.NormalizeColumns<Columns>
+  }>
+  <const Columns extends string | readonly string[]>(
+    spec: RichUniqueInput<Columns>
+  ): BaseTable.TableOption
+} = ((input: unknown) =>
+  isObject(input) && "columns" in input && ("name" in input || "nullsNotDistinct" in input || "deferrable" in input || "initiallyDeferred" in input)
+    ? BaseTable.option({
+        kind: "unique",
+        columns: normalizeColumns((input as RichUniqueInput<string | readonly string[]>).columns),
+        name: (input as RichUniqueInput<string | readonly string[]>).name,
+        nullsNotDistinct: (input as RichUniqueInput<string | readonly string[]>).nullsNotDistinct,
+        deferrable: (input as RichUniqueInput<string | readonly string[]>).deferrable,
+        initiallyDeferred: (input as RichUniqueInput<string | readonly string[]>).initiallyDeferred
+      })
+    : BaseTable.unique(input as string | readonly string[])) as never
+
+export const index: {
+  <const Columns extends string | readonly string[]>(
+    columns: Columns
+  ): BaseTable.TableOption<{
+    readonly kind: "index"
+    readonly columns: BaseTable.NormalizeColumns<Columns>
+  }>
+  <Table extends SchemaTable, const Columns extends string | readonly string[]>(
+    spec: Omit<RichIndexInput<Columns>, "predicate"> & {
+      readonly predicate: TableExpressionFactory<Table>
+    }
+  ): TableScopedOptionBuilder<Table, {
+    readonly kind: "index"
+    readonly columns?: BaseTable.NormalizeColumns<Columns>
+    readonly keys?: readonly [BaseTable.IndexKeySpec, ...BaseTable.IndexKeySpec[]]
+    readonly name?: string
+    readonly unique?: boolean
+    readonly method?: string
+    readonly include?: readonly string[]
+    readonly predicate?: DdlExpressionLike
+  }>
+  <const Columns extends string | readonly string[]>(
+    spec: RichIndexInput<Columns>
+  ): BaseTable.TableOption
+} = ((input: unknown) =>
+  isObject(input) && ("keys" in input || "name" in input || "unique" in input || "method" in input || "include" in input || "predicate" in input)
+    ? (() => {
+        const spec = input as RichIndexInput<string | readonly string[]> & {
+          readonly predicate?: DdlExpressionLike | TableExpressionFactory<SchemaTable>
+        }
+        const predicate = spec.predicate
+        const placeholder = {
+          kind: "index" as const,
+          columns: spec.columns === undefined
+            ? undefined
+            : normalizeColumns(spec.columns),
+          keys: spec.keys === undefined
+            ? undefined
+            : normalizeIndexKeys(spec.keys),
+          name: spec.name,
+          unique: spec.unique,
+          method: spec.method,
+          include: spec.include,
+          predicate: predicate as unknown as DdlExpressionLike
+        }
+        return isTableExpressionFactory(predicate)
+          ? makeTableScopedOption(placeholder, (table) => ({
+              ...placeholder,
+              predicate: predicate(table.columns)
+            }))
+          : BaseTable.option({
+              ...placeholder,
+              predicate
+            })
+      })()
+    : BaseTable.index(input as string | readonly string[])) as never
+export const foreignKey = <
+  const LocalColumns extends string | readonly string[],
+  TargetTable extends AnyTable,
+  const TargetColumns extends string | readonly string[]
 >(
-  columns: LocalColumns,
-  target: () => TargetTable,
-  referencedColumns: TargetColumns
+  columnsOrSpec: LocalColumns | RichForeignKeyInput<LocalColumns, TargetTable, TargetColumns>,
+  target?: () => TargetTable,
+  referencedColumns?: TargetColumns
 ): BaseTable.TableOption =>
-  BaseTable.foreignKey(columns, target as () => BaseTable.AnyTable, referencedColumns)
+  isObject(columnsOrSpec) && "columns" in columnsOrSpec && "target" in columnsOrSpec
+    ? (() => {
+        const spec = columnsOrSpec as RichForeignKeyInput<LocalColumns, TargetTable, TargetColumns>
+        const targetTable = spec.target() as BaseTable.AnyTable
+        const targetState = targetTable[BaseTable.TypeId]
+        return BaseTable.option({
+        kind: "foreignKey",
+        columns: normalizeColumns(spec.columns),
+        name: spec.name,
+        references: () => ({
+          tableName: targetState.baseName,
+          schemaName: targetState.schemaName,
+          columns: normalizeColumns(spec.referencedColumns),
+          knownColumns: Object.keys(targetState.fields)
+        }),
+        onUpdate: spec.onUpdate,
+        onDelete: spec.onDelete,
+        deferrable: spec.deferrable,
+        initiallyDeferred: spec.initiallyDeferred
+      })
+      })()
+    : BaseTable.foreignKey(
+        columnsOrSpec as LocalColumns,
+        target as () => BaseTable.AnyTable,
+        referencedColumns as TargetColumns
+      )
 
-export const check = BaseTable.check
+export const check: {
+  <Name extends string>(name: Name, predicate: DdlExpressionLike): BaseTable.TableOption
+  <Name extends string, Table extends SchemaTable>(
+    name: Name,
+    predicate: TableExpressionFactory<Table>
+  ): TableScopedOptionBuilder<Table, {
+    readonly kind: "check"
+    readonly name: Name
+    readonly predicate: DdlExpressionLike
+  }>
+  <Name extends string, Table extends SchemaTable>(
+    spec: Omit<RichCheckInput<Name>, "predicate"> & {
+      readonly predicate: TableExpressionFactory<Table>
+    }
+  ): TableScopedOptionBuilder<Table, {
+    readonly kind: "check"
+    readonly name: Name
+    readonly predicate: DdlExpressionLike
+    readonly noInherit?: boolean
+  }>
+  <Name extends string>(spec: RichCheckInput<Name>): BaseTable.TableOption
+} = ((nameOrSpec: string | RichCheckInput, predicate?: DdlExpressionLike) =>
+  isObject(nameOrSpec)
+    ? (() => {
+        const spec = nameOrSpec as RichCheckInput & {
+          readonly predicate: DdlExpressionLike | TableExpressionFactory<SchemaTable>
+        }
+        const specPredicate = spec.predicate
+        const placeholder = {
+          kind: "check" as const,
+          name: spec.name,
+          predicate: specPredicate as unknown as DdlExpressionLike,
+          noInherit: spec.noInherit
+        }
+        return isTableExpressionFactory(specPredicate)
+          ? makeTableScopedOption(placeholder, (table) => ({
+              ...placeholder,
+              predicate: specPredicate(table.columns)
+            }))
+          : BaseTable.option({
+              ...placeholder,
+              predicate: specPredicate
+            })
+      })()
+    : (() => {
+        const predicateOrFactory = predicate as DdlExpressionLike | TableExpressionFactory<SchemaTable>
+        const placeholder = {
+          kind: "check" as const,
+          name: nameOrSpec,
+          predicate: predicateOrFactory as unknown as DdlExpressionLike
+        }
+        return isTableExpressionFactory(predicateOrFactory)
+          ? makeTableScopedOption(placeholder, (table) => ({
+              ...placeholder,
+              predicate: predicateOrFactory(table.columns)
+            }))
+          : BaseTable.option({
+              ...placeholder,
+              predicate: predicateOrFactory
+            })
+      })()) as never
 
 export type SelectOf<Table extends { readonly schemas: { readonly select: Schema.Schema<any> } }> = BaseTable.SelectOf<Table>
 export type InsertOf<Table extends { readonly schemas: { readonly insert: Schema.Schema<any> } }> = BaseTable.InsertOf<Table>

package/src/postgres/type.ts

@@ -0,0 +1,31 @@
+import type * as Expression from "../internal/scalar.js"
+import { postgresDatatypes } from "./datatypes/index.js"
+import { type as postgresType } from "./internal/dsl.js"
+
+type PostgresTypeNamespace = typeof postgresDatatypes & {
+  readonly array: <Element extends Expression.DbType.Any>(
+    element: Element
+  ) => Expression.DbType.Array<"postgres", Element, `${Element["kind"]}[]`>
+  readonly range: <Kind extends string, Subtype extends Expression.DbType.Any>(
+    kind: Kind,
+    subtype: Subtype
+  ) => Expression.DbType.Range<"postgres", Subtype, Kind>
+  readonly multirange: <Kind extends string, Subtype extends Expression.DbType.Any>(
+    kind: Kind,
+    subtype: Subtype
+  ) => Expression.DbType.Multirange<"postgres", Subtype, Kind>
+  readonly record: <Kind extends string, Fields extends Record<string, Expression.DbType.Any>>(
+    kind: Kind,
+    fields: Fields
+  ) => Expression.DbType.Composite<"postgres", Fields, Kind>
+  readonly domain: <Kind extends string, Base extends Expression.DbType.Any>(
+    kind: Kind,
+    base: Base
+  ) => Expression.DbType.Domain<"postgres", Base, Kind>
+  readonly enum: <Kind extends string>(kind: Kind) => Expression.DbType.Enum<"postgres", Kind>
+  readonly set: <Kind extends string>(kind: Kind) => Expression.DbType.Set<"postgres", Kind>
+  readonly custom: <Kind extends string>(kind: Kind) => Expression.DbType.Base<"postgres", Kind>
+}
+
+/** Postgres database-type constructors for casts and typed column references. */
+export const type: PostgresTypeNamespace = postgresType

package/src/postgres.ts

@@ -4,16 +4,32 @@ export * as Column from "./postgres/column.js"
 export * as Datatypes from "./postgres/datatypes/index.js"
 /** Postgres SQLSTATE catalog and error normalization helpers. */
 export * as Errors from "./postgres/errors/index.js"
-/** Shared scalar SQL expression interfaces and DB-type descriptors. */
-export * as Expression from "./internal/expression.js"
+/** Shared scalar SQL interfaces and DB-type descriptors. */
+export * as Scalar from "./internal/scalar.js"
+/** Postgres cast helpers. */
+export { cast as Cast } from "./postgres/cast.js"
 /** Postgres-specialized SQL function expressions. */
 export * as Function from "./postgres/function/index.js"
+/** Postgres-specialized JSON expression helpers. */
+export * as Json from "./postgres/json.js"
 /** Postgres-specialized typed query execution contracts. */
 export * as Executor from "./postgres/executor.js"
-/** Shared logical query-plan interfaces. */
-export * as Plan from "./internal/plan.js"
+/** Shared logical row-set interfaces. */
+export * as RowSet from "./internal/row-set.js"
 /** Postgres-specialized query-construction DSL. */
 export * as Query from "./postgres/query.js"
+/** Postgres database-type constructors for casts and typed references. */
+export { type as Type } from "./postgres/type.js"
+/** Postgres normalized table/enum metadata helpers. */
+export * as Metadata from "./postgres/metadata.js"
+/** Postgres schema-expression helpers for DDL-only metadata. */
+export * as SchemaExpression from "./postgres/schema-expression.js"
+/** Postgres schema-scoped table and enum builder helpers. */
+export { schema } from "./postgres/schema.js"
+export type { SchemaNamespace } from "./postgres/schema.js"
+/** Postgres enum and sequence definition helpers. */
+export { enumType as enum, sequence } from "./postgres/schema-management.js"
+export type { EnumDefinition, SequenceDefinition } from "./postgres/schema-management.js"
 /** Postgres-specialized table-definition DSL. */
 export * as Table from "./postgres/table.js"
 /** Postgres-specialized built-in renderer entrypoint. */

package/CHANGELOG.md

@@ -1,134 +0,0 @@
-# Changelog
-
-All notable changes to this project are documented here.
-
-## Unreleased
-
-## 0.13.0 - 2026-03-23
-
-### Breaking Changes
-
-- feat(api)!: move json helpers under Function namespaces
-- feat(api)!: move scalar helpers under Function namespaces
-- feat(column)!: require expressions for default and generated
-- fix(table)!: require expressions for check constraints
-
-### Fixes
-
-- fix(release): use personal git identity
-- fix(release): fall back to release commits when tags are missing
-
-### Docs
-
-- docs(readme): add postgres functions and defaults note
-- docs(readme): add shaping results imports
-- docs(readme): restructure intro and refresh examples
-- docs(readme): document table options and check constraints
-
-## 0.12.3 - 2026-03-21
-
-### Breaking Changes
-
-- feat(query)!: add schema-free implication typing and derived tables
-- feat(query)!: add dialect-aware coercion guards for operators
-- feat(table)!: split postgres and mysql table namespaces
-- feat(query)!: replace insert helpers with composable values sources
-- feat(query)!: remove insertUnnest helper
-- feat(api)!: remove root exports in favor of dialect entrypoints
-- feat(api)!: move shared core modules into internal
-- refactor(api)!: rename dialect modules to lowercase
-- feat(api)!: remove root export map
-- feat(query)!: simplify insert source composition
-- feat(executor)!: simplify dialect executor construction
-- feat(runtime)!: normalize executor outputs and enforce runtime schemas
-- feat(query)!: replace hasDefault with default helper
-
-### Features
-
-- feat(mysql): add mysql errors and rename modules snake_case
-- feat(query): add read predicate builders and rendering
-- feat(query): add common table expressions
-- feat(query): add mutation statements and returning
-- feat(query): add pagination, set ops, joins, windows, and ddl
-- feat(query): add correlated sources and statement clauses
-- feat(query): add data-modifying ctes and transaction helper
-- feat(executor): add savepoint helper
-- feat(query): add remaining read predicates and simple case
-- feat(query): expand dialect datatype witnesses and runtime mapping
-- feat(datatypes): model broader dialect catalogs
-- feat(datatypes): model structured types and coercion
-- feat(json): add postgres json operators and typed manipulation
-- feat(table): add schema-qualified table namespaces
-- feat(query): add truncate merge and transaction statements
-- feat(query): add insert sources and conflict helpers
-- feat(query): add standalone sources and quantified subqueries
-- feat(query): add distinct on support
-- feat(query): add curried aliases and preserve literal outputs
-- feat(query): add curried cte source helpers
-- feat(postgres): add function namespace for typed SQL expressions
-- feat(release): use changelog section as GitHub release body
-
-### Fixes
-
-- fix(integration): run Bun tests by explicit path
-- fix(integration): extend live database timeouts
-
-### Refactors
-
-- refactor(datatypes): derive coercion from family specs
-- refactor(predicate): rewrite implication analysis around a stack walk
-- refactor(modules): use js-relative specifiers across source files
-- refactor(modules): split public and internal surfaces
-
-### Docs
-
-- docs: expand README with type-safety and query return examples
-- docs(readme): document derived tables and type-driven queries
-- docs(readme): document extended read predicates
-- docs(readme): document common table expressions
-- docs(readme): document pagination, set ops, joins, windows, and ddl
-- docs(readme): document correlated sources and statement clauses
-- docs(readme): document data-modifying ctes and transactions
-- docs(readme): restructure guide around type safety
-- docs: add AGENTS instructions
-- docs(readme): add semantic SQL hook and native-preview commands
-- docs(readme): update package layout docs
-- docs(readme): strengthen proof-oriented examples
-- docs(readme): align examples with the new query surface
-- docs(readme): show dialect mismatch at executor boundary
-- docs(readme): fix json mutation example semantics
-- docs(readme): make predicate narrowing example self-contained
-- docs(readme): use pipe style in mutation examples
-- docs(readme): document onboarding and error handling
-- docs(readme): refresh schema integration and package usage
-- docs(readme): use pipe style in returning examples
-- docs(readme): align guide examples with current query api
-- docs(readme): add npm install commands
-
-### Tests
-
-- test(mutations): cover json mutation compatibility
-- test(json): add exact mutation render coverage
-- test: harden json and type coverage
-- test: split query coverage and centralize assertions
-- test(json): add reusable path object coverage
-- test(integration): add docker-backed database coverage
-
-### Build
-
-- build(package): define npm publish layout for 0.12.3
-
-### CI
-
-- ci: add github actions workflow for tests and build
-
-### Chores
-
-- chore(types): switch typecheck to tsgo and trim depth-heavy tests
-
-### Other
-
-- Bootstrap effect-db with typed SQL core and dialect renderers
-- Rename package to effect-qb and tighten query type semantics
-- Implement predicate analysis and Postgres error normalization
-