turbine-orm 0.27.0 → 0.28.0

package/dist/generate.js

@@ -10,11 +10,29 @@
  */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
-import { singularize, snakeToPascal } from './schema.js';
+import { pgTypeToTs, singularize, snakeToPascal, } from './schema.js';
 /** Get the TypeScript type name for a table (singularized PascalCase) */
 function entityName(tableName) {
     return snakeToPascal(singularize(tableName));
 }
+/**
+ * Resolve the TypeScript type for a column, mapping enum-typed columns to their
+ * generated string-literal union (PascalCase enum name) instead of the
+ * `unknown` that {@link pgTypeToTs} yields for user-defined types. Falls back to
+ * the introspected `col.tsType` for every non-enum column.
+ */
+function columnTsType(col, enums) {
+    const dt = col.dialectType ?? col.pgType;
+    const isArray = col.isArray || dt.startsWith('_');
+    const base = isArray && dt.startsWith('_') ? dt.slice(1) : dt;
+    if (Object.hasOwn(enums, base)) {
+        let t = snakeToPascal(base);
+        if (isArray)
+            t += '[]';
+        return col.nullable ? `${t} | null` : t;
+    }
+    return col.tsType;
+}
 /** Escape a value for embedding in a single-quoted TypeScript string literal */
 function escSQ(value) {
     return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
@@ -44,6 +62,12 @@ export function generate(options) {
     const indexContent = generateIndex(options.schema);
     writeFileSync(join(outDir, 'index.ts'), indexContent, 'utf-8');
     files.push('index.ts');
+    // Generate zod.ts (optional — --zod flag)
+    if (options.zod) {
+        const zodContent = generateZod(options.schema);
+        writeFileSync(join(outDir, 'zod.ts'), zodContent, 'utf-8');
+        files.push('zod.ts');
+    }
     return { outDir, files };
 }
 // ---------------------------------------------------------------------------
@@ -104,7 +128,7 @@ export function generateTypes(schema) {
             const pkNote = table.primaryKey.includes(col.name) ? ' (primary key)' : '';
             const nullNote = col.nullable ? ' (nullable)' : '';
             lines.push(`  /** Column: ${col.name} — ${col.pgType}${pkNote}${nullNote} */`);
-            lines.push(`  ${col.field}: ${col.tsType};`);
+            lines.push(`  ${col.field}: ${columnTsType(col, schema.enums)};`);
         }
         lines.push('}');
         lines.push('');
@@ -114,15 +138,18 @@ export function generateTypes(schema) {
         lines.push(`/** Input type for creating a row in \`${table.name}\` */`);
         lines.push(`export type ${typeName}Create = {`);
         for (const col of table.columns) {
+            // STORED generated columns are computed by the database — never writable.
+            if (col.isGeneratedStored)
+                continue;
             const isPk = table.primaryKey.includes(col.name);
             const isOptional = col.hasDefault || col.nullable || isPk;
             if (isOptional) {
                 const reason = isPk ? 'auto-generated' : col.hasDefault ? 'has default' : 'nullable';
                 lines.push(`  /** Optional: ${reason} */`);
-                lines.push(`  ${col.field}?: ${col.tsType};`);
+                lines.push(`  ${col.field}?: ${columnTsType(col, schema.enums)};`);
             }
             else {
-                lines.push(`  ${col.field}: ${col.tsType};`);
+                lines.push(`  ${col.field}: ${columnTsType(col, schema.enums)};`);
             }
         }
         lines.push('};');
@@ -130,11 +157,11 @@ export function generateTypes(schema) {
         // --- Update input type (all fields optional except PK) ---
         // Numeric columns additionally accept `UpdateOperatorInput<number>` so
         // users can write `{ viewCount: { increment: 1 } }` without an `as any`.
-        const nonPkCols = table.columns.filter((c) => !table.primaryKey.includes(c.name));
+        const nonPkCols = table.columns.filter((c) => !table.primaryKey.includes(c.name) && !c.isGeneratedStored);
         lines.push(`/** Input type for updating a row in \`${table.name}\` */`);
         lines.push(`export type ${typeName}Update = {`);
         for (const col of nonPkCols) {
-            lines.push(`  ${col.field}?: ${updateFieldType(col.tsType)};`);
+            lines.push(`  ${col.field}?: ${updateFieldType(columnTsType(col, schema.enums))};`);
         }
         lines.push('};');
         lines.push('');
@@ -267,9 +294,122 @@ export function generateTypes(schema) {
     return lines.join('\n');
 }
 // ---------------------------------------------------------------------------
+// zod.ts generator (H1 — `turbine generate --zod`)
+// ---------------------------------------------------------------------------
+/**
+ * Map a TypeScript primitive (as produced by {@link pgTypeToTs}) to its Zod
+ * expression. `Date` uses `z.coerce.date()` — the generated schemas double as
+ * request-body validators where dates arrive as ISO strings, and coercion keeps
+ * both a `Date` and a valid date-string acceptable (documented decision).
+ */
+function zodScalar(ts) {
+    switch (ts) {
+        case 'number':
+            return 'z.number()';
+        case 'string':
+            return 'z.string()';
+        case 'boolean':
+            return 'z.boolean()';
+        case 'Date':
+            return 'z.coerce.date()';
+        case 'bigint':
+            return 'z.bigint()';
+        case 'Buffer':
+            return 'z.instanceof(Uint8Array)';
+        case 'number[]':
+            // pgvector — `pgTypeToTs('vector')` yields `number[]`.
+            return 'z.array(z.number())';
+        default:
+            // json/jsonb and any unmapped user-defined type.
+            return 'z.unknown()';
+    }
+}
+/**
+ * Base Zod expression for a column, resolving enums → `z.enum([...])`, arrays →
+ * `.array()`, and vectors → `z.array(z.number())`. Does NOT append
+ * `.nullable()` / `.optional()` — callers layer those on per-schema.
+ */
+function zodBaseType(col, enums) {
+    const dt = col.dialectType ?? col.pgType;
+    const isArray = col.isArray || dt.startsWith('_');
+    const base = isArray && dt.startsWith('_') ? dt.slice(1) : dt;
+    let expr;
+    if (Object.hasOwn(enums, base)) {
+        expr = `z.enum([${enums[base].map((l) => `'${escSQ(l)}'`).join(', ')}])`;
+    }
+    else {
+        expr = zodScalar(pgTypeToTs(base, false));
+    }
+    if (isArray)
+        expr += '.array()';
+    return expr;
+}
+/**
+ * Generate the contents of `zod.ts`. Emits, per table, `XSchema` (the full
+ * row), `XCreateSchema` (PK/defaulted/nullable columns optional, STORED
+ * generated columns omitted), and `XUpdateSchema` (PK + STORED generated
+ * columns omitted, every remaining column optional). Exported so tests can pin
+ * the output without writing files.
+ */
+export function generateZod(schema) {
+    const lines = [...generatedFileHeader()];
+    // `zod` is a USER dependency — this generated file imports it, but the Turbine
+    // library runtime never does, so Zod stays out of the package's dep graph.
+    lines.push("import { z } from 'zod';");
+    lines.push('');
+    for (const table of Object.values(schema.tables)) {
+        const typeName = entityName(table.name);
+        // Full-row schema.
+        lines.push(`/** Zod schema for a \`${table.name}\` row */`);
+        lines.push(`export const ${typeName}Schema = z.object({`);
+        for (const col of table.columns) {
+            let expr = zodBaseType(col, schema.enums);
+            if (col.nullable)
+                expr += '.nullable()';
+            lines.push(`  ${col.field}: ${expr},`);
+        }
+        lines.push('});');
+        lines.push('');
+        // Create schema — STORED generated columns can never be written; PK,
+        // defaulted, and nullable columns are optional.
+        lines.push(`/** Zod schema for creating a \`${table.name}\` row */`);
+        lines.push(`export const ${typeName}CreateSchema = z.object({`);
+        for (const col of table.columns) {
+            if (col.isGeneratedStored)
+                continue;
+            const isPk = table.primaryKey.includes(col.name);
+            let expr = zodBaseType(col, schema.enums);
+            if (col.nullable)
+                expr += '.nullable()';
+            if (col.hasDefault || col.nullable || isPk)
+                expr += '.optional()';
+            lines.push(`  ${col.field}: ${expr},`);
+        }
+        lines.push('});');
+        lines.push('');
+        // Update schema — PK and STORED generated columns omitted; all else optional.
+        lines.push(`/** Zod schema for updating a \`${table.name}\` row */`);
+        lines.push(`export const ${typeName}UpdateSchema = z.object({`);
+        for (const col of table.columns) {
+            if (col.isGeneratedStored)
+                continue;
+            if (table.primaryKey.includes(col.name))
+                continue;
+            let expr = zodBaseType(col, schema.enums);
+            if (col.nullable)
+                expr += '.nullable()';
+            expr += '.optional()';
+            lines.push(`  ${col.field}: ${expr},`);
+        }
+        lines.push('});');
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
 // metadata.ts generator
 // ---------------------------------------------------------------------------
-function generateMetadata(schema) {
+export function generateMetadata(schema) {
     const lines = [
         ...generatedFileHeader(),
         "import type { SchemaMetadata } from 'turbine-orm';",
@@ -348,6 +488,9 @@ function generateMetadata(schema) {
             lines.push(`        { name: '${escSQ(idx.name)}', columns: [${idx.columns.map((c) => `'${escSQ(c)}'`).join(', ')}], unique: ${idx.unique}, definition: ${JSON.stringify(idx.definition)} },`);
         }
         lines.push('      ],');
+        // isView — read-only marker; the runtime write guard reads it.
+        if (table.isView)
+            lines.push('      isView: true,');
         lines.push('    },');
     }
     lines.push('  },');
@@ -368,7 +511,7 @@ function generateMetadata(schema) {
 // ---------------------------------------------------------------------------
 // index.ts generator (configured client with typed table accessors)
 // ---------------------------------------------------------------------------
-function generateIndex(schema) {
+export function generateIndex(schema) {
     const tableEntries = Object.values(schema.tables);
     const lines = [
         ...generatedFileHeader(),
@@ -405,7 +548,7 @@ function generateIndex(schema) {
         const hasRelations = Object.keys(table.relations).length > 0;
         const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
         lines.push(`  /** Query interface for the \`${table.name}\` table (transaction-scoped) */`);
-        lines.push(`  declare readonly ${accessor}: QueryInterface<${genericArgs}>;`);
+        lines.push(`  declare readonly ${accessor}: ${accessorType(table, genericArgs)};`);
     }
     lines.push('}');
     lines.push('');
@@ -447,7 +590,7 @@ function generateIndex(schema) {
         const hasRelations = Object.keys(table.relations).length > 0;
         const genericArgs = hasRelations ? `${typeName}, ${typeName}Relations` : typeName;
         lines.push(`  /** Query interface for the \`${table.name}\` table */`);
-        lines.push(`  declare readonly ${accessor}: QueryInterface<${genericArgs}>;`);
+        lines.push(`  declare readonly ${accessor}: ${accessorType(table, genericArgs)};`);
     }
     lines.push('');
     lines.push('  constructor(config?: TurbineConfig) {');
@@ -491,6 +634,18 @@ function generateIndex(schema) {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+/**
+ * The generated table-accessor type. A view (`isView`) without a primary key
+ * cannot be looked up by unique key, so its `findUnique`-family methods are
+ * excluded via `Omit`. Everything else is a plain `QueryInterface<…>`.
+ */
+function accessorType(table, genericArgs) {
+    const base = `QueryInterface<${genericArgs}>`;
+    if (table.isView && table.primaryKey.length === 0) {
+        return `Omit<${base}, 'findUnique' | 'findUniqueOrThrow'>`;
+    }
+    return base;
+}
 function serializeColumn(col) {
     const parts = [
         `name: '${escSQ(col.name)}'`,
@@ -508,6 +663,12 @@ function serializeColumn(col) {
     // output stays byte-identical for the common client-default columns.
     if (col.isGenerated)
         parts.push(`isGenerated: true`);
+    // STORED generated columns — the runtime write guard reads isGeneratedStored.
+    if (col.isGeneratedStored)
+        parts.push(`isGeneratedStored: true`);
+    if (col.generationExpression !== undefined) {
+        parts.push(`generationExpression: '${escSQ(col.generationExpression)}'`);
+    }
     if (col.maxLength !== undefined)
         parts.push(`maxLength: ${col.maxLength}`);
     return `{ ${parts.join(', ')} }`;

package/dist/index.d.ts

@@ -43,11 +43,12 @@ export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
 export type { ObserveConfig, ObserveHandle } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
-export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GroupByArgs, type HavingClause, type JsonFilter, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
+export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByArgs, type HavingClause, type JsonFilter, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';
-export type { ColumnMetadata, IndexMetadata, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
+export type { CheckMetadata, ColumnMetadata, IndexMetadata, ReferentialAction, RelationDef, SchemaMetadata, TableMetadata, } from './schema.js';
 export { camelToSnake, isDateType, normalizeKeyColumns, pgArrayType, pgTypeToTs, singularize, snakeToCamel, snakeToPascal, } from './schema.js';
-export { applyManyToManyRelations, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, defineSchema, type ManyToManyDef, type SchemaDef, type TableDef, table, } from './schema-builder.js';
+export { applyManyToManyRelations, type CheckDef, ColumnBuilder, type ColumnConfig, type ColumnDef, type ColumnType, type ColumnTypeName, column, type DefineSchemaOptions, defineSchema, type ManyToManyDef, type ReferenceDef, type SchemaDef, type TableDef, table, } from './schema-builder.js';
 export { type AlterColumnDef, type AlterDef, type DiffResult, type PushResult, type SchemaSqlOptions, schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
+export { type DefinedSeed, defineSeed, type SeedFunction } from './seed.js';
 export { type TurbineHttpOptions, turbineHttp } from './serverless.js';
 export { buildTypedSql, TypedSqlQuery } from './typed-sql.js';

package/dist/index.js

@@ -58,6 +58,8 @@ export { applyManyToManyRelations, ColumnBuilder, column, defineSchema,
 table, } from './schema-builder.js';
 // Schema SQL — generate DDL, diff, and push
 export { schemaDiff, schemaPush, schemaToSQL, schemaToSQLString, } from './schema-sql.js';
+// Seed helper
+export { defineSeed } from './seed.js';
 // Serverless / edge factory
 export { turbineHttp } from './serverless.js';
 // Typed raw SQL — Turbine's TypedSQL escape hatch

package/dist/introspect.d.ts

@@ -8,7 +8,13 @@
  * This is the foundation of `npx turbine generate`.
  */
 import { type Dialect } from './dialect.js';
-import { type SchemaMetadata } from './schema.js';
+import { type ReferentialAction, type SchemaMetadata } from './schema.js';
+/**
+ * Map a `pg_constraint.confdeltype` / `confupdtype` character to a
+ * {@link ReferentialAction}. Postgres encodes: `a` = NO ACTION, `r` = RESTRICT,
+ * `c` = CASCADE, `n` = SET NULL, `d` = SET DEFAULT.
+ */
+export declare function pgConfActionToReferential(ch: string): ReferentialAction;
 export interface IntrospectOptions {
     /** Postgres connection string */
     connectionString: string;
@@ -18,6 +24,13 @@ export interface IntrospectOptions {
     include?: string[];
     /** Tables to exclude (default: none). Applied after include. */
     exclude?: string[];
+    /**
+     * Also introspect **views** and **materialized views** as read-only
+     * {@link TableMetadata} entries (`isView: true`). Off by default. Write
+     * builders reject views (E003); a view without a primary key is excluded from
+     * the generated `findUnique`-family accessor types.
+     */
+    includeViews?: boolean;
     /**
      * Dialect whose {@link Dialect.introspector} drives the catalog reads.
      * Defaults to {@link postgresDialect}. Engines plug their own introspector
@@ -37,3 +50,9 @@ export declare function introspect(options: IntrospectOptions): Promise<SchemaMe
  * `postgresDialect.introspector`; call {@link introspect} for dialect routing.
  */
 export declare function introspectPostgresCatalog(options: IntrospectOptions): Promise<SchemaMetadata>;
+/**
+ * Recover the raw check expression from `pg_get_constraintdef` output, which
+ * wraps it as `CHECK ((expr))`. Strips the leading `CHECK ` keyword and one
+ * balanced outer paren pair; leaves anything unexpected untouched.
+ */
+export declare function stripCheckWrapper(def: string): string;

package/dist/introspect.js

@@ -10,6 +10,25 @@
 import pg from 'pg';
 import { postgresDialect } from './dialect.js';
 import { isDateType, pgTypeToTs, singularize, snakeToCamel, } from './schema.js';
+/**
+ * Map a `pg_constraint.confdeltype` / `confupdtype` character to a
+ * {@link ReferentialAction}. Postgres encodes: `a` = NO ACTION, `r` = RESTRICT,
+ * `c` = CASCADE, `n` = SET NULL, `d` = SET DEFAULT.
+ */
+export function pgConfActionToReferential(ch) {
+    switch (ch) {
+        case 'c':
+            return 'cascade';
+        case 'r':
+            return 'restrict';
+        case 'n':
+            return 'set null';
+        case 'd':
+            return 'set default';
+        default:
+            return 'no action';
+    }
+}
 // ---------------------------------------------------------------------------
 // SQL queries (all parameterized, no interpolation)
 // ---------------------------------------------------------------------------
@@ -29,6 +48,8 @@ const SQL_COLUMNS = `
     is_nullable,
     column_default,
     is_identity,
+    is_generated,
+    generation_expression,
     ordinal_position,
     character_maximum_length
   FROM information_schema.columns
@@ -84,6 +105,65 @@ const SQL_INDEXES = `
   FROM pg_indexes
   WHERE schemaname = $1
 `;
+// Foreign-key referential actions (ON DELETE / ON UPDATE) live in pg_catalog,
+// not information_schema. Keyed by constraint name for join with SQL_FOREIGN_KEYS.
+const SQL_FK_ACTIONS = `
+  SELECT con.conname, con.confdeltype, con.confupdtype
+  FROM pg_constraint con
+  JOIN pg_catalog.pg_namespace n ON n.oid = con.connamespace
+  WHERE con.contype = 'f'
+    AND n.nspname = $1
+`;
+// CHECK constraints (contype = 'c'). NOT NULL is stored as attnotnull, not a
+// check constraint, so it never appears here.
+const SQL_CHECKS = `
+  SELECT rel.relname AS table_name, con.conname, pg_get_constraintdef(con.oid) AS definition
+  FROM pg_constraint con
+  JOIN pg_catalog.pg_class rel ON rel.oid = con.conrelid
+  JOIN pg_catalog.pg_namespace n ON n.oid = con.connamespace
+  WHERE con.contype = 'c'
+    AND n.nspname = $1
+`;
+// Views (relkind 'v') — column metadata comes free from information_schema.columns.
+const SQL_VIEWS = `
+  SELECT table_name
+  FROM information_schema.views
+  WHERE table_schema = $1
+  ORDER BY table_name
+`;
+// Materialized views (relkind 'm') — NOT in information_schema; read from pg_catalog.
+const SQL_MATVIEWS = `
+  SELECT matviewname AS table_name
+  FROM pg_matviews
+  WHERE schemaname = $1
+  ORDER BY matviewname
+`;
+// Materialized-view columns — information_schema.columns omits matviews, so pull
+// them from pg_attribute. Aliased to mirror SQL_COLUMNS so the same row-mapping
+// applies (array types surface as data_type 'ARRAY' + a '_'-prefixed udt_name).
+const SQL_MATVIEW_COLUMNS = `
+  SELECT
+    c.relname AS table_name,
+    a.attname AS column_name,
+    t.typname AS udt_name,
+    CASE WHEN t.typcategory = 'A' THEN 'ARRAY' ELSE 'base' END AS data_type,
+    CASE WHEN a.attnotnull THEN 'NO' ELSE 'YES' END AS is_nullable,
+    NULL AS column_default,
+    'NO' AS is_identity,
+    'NEVER' AS is_generated,
+    NULL AS generation_expression,
+    a.attnum AS ordinal_position,
+    NULL::int AS character_maximum_length
+  FROM pg_catalog.pg_attribute a
+  JOIN pg_catalog.pg_class c ON c.oid = a.attrelid
+  JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+  JOIN pg_catalog.pg_type t ON t.oid = a.atttypid
+  WHERE n.nspname = $1
+    AND c.relkind = 'm'
+    AND a.attnum > 0
+    AND NOT a.attisdropped
+  ORDER BY c.relname, a.attnum
+`;
 const SQL_ENUMS = `
   SELECT t.typname, e.enumlabel
   FROM pg_type t
@@ -124,17 +204,45 @@ export async function introspectPostgresCatalog(options) {
     });
     try {
         // Run all information_schema queries in parallel
-        const [tablesResult, columnsResult, pkResult, fkResult, uniqueResult, indexResult, enumResult] = await Promise.all([
+        const [tablesResult, columnsResult, pkResult, fkResult, fkActionsResult, uniqueResult, indexResult, checkResult, enumResult,] = await Promise.all([
             pool.query(SQL_TABLES, [schema]),
             pool.query(SQL_COLUMNS, [schema]),
             pool.query(SQL_PRIMARY_KEYS, [schema]),
             pool.query(SQL_FOREIGN_KEYS, [schema]),
+            pool.query(SQL_FK_ACTIONS, [schema]),
             pool.query(SQL_UNIQUE_CONSTRAINTS, [schema]),
             pool.query(SQL_INDEXES, [schema]),
+            pool.query(SQL_CHECKS, [schema]),
             pool.query(SQL_ENUMS, [schema]),
         ]);
-        // Filter tables by include/exclude
-        let tableNames = tablesResult.rows.map((r) => r.table_name);
+        // Views + materialized views (opt-in). Regular-view columns are already in
+        // columnsResult (information_schema.columns); matview columns need a separate
+        // pg_catalog read, which we splice into the column rows below.
+        const viewNameSet = new Set();
+        const matviewColumnRows = [];
+        if (options.includeViews) {
+            const [viewsResult, matviewsResult, matviewColsResult] = await Promise.all([
+                pool.query(SQL_VIEWS, [schema]),
+                pool.query(SQL_MATVIEWS, [schema]),
+                pool.query(SQL_MATVIEW_COLUMNS, [schema]),
+            ]);
+            for (const r of viewsResult.rows)
+                viewNameSet.add(r.table_name);
+            for (const r of matviewsResult.rows)
+                viewNameSet.add(r.table_name);
+            matviewColumnRows.push(...matviewColsResult.rows);
+        }
+        // constraint_name → { onDelete, onUpdate } referential actions.
+        const fkActions = new Map();
+        for (const row of fkActionsResult.rows) {
+            fkActions.set(row.conname, {
+                onDelete: pgConfActionToReferential(row.confdeltype),
+                onUpdate: pgConfActionToReferential(row.confupdtype),
+            });
+        }
+        // Filter tables by include/exclude. Views/matviews join the base tables as
+        // candidates so include/exclude apply uniformly.
+        let tableNames = [...tablesResult.rows.map((r) => r.table_name), ...viewNameSet];
         if (options.include?.length) {
             const includeSet = new Set(options.include);
             tableNames = tableNames.filter((t) => includeSet.has(t));
@@ -145,8 +253,10 @@ export async function introspectPostgresCatalog(options) {
         }
         const tableSet = new Set(tableNames);
         // ----- Group columns by table -----
+        // Base-table + regular-view columns come from information_schema.columns;
+        // materialized-view columns are appended from the pg_catalog read.
         const columnsByTable = new Map();
-        for (const row of columnsResult.rows) {
+        for (const row of [...columnsResult.rows, ...matviewColumnRows]) {
             const tableName = row.table_name;
             if (!tableSet.has(tableName))
                 continue;
@@ -169,6 +279,11 @@ export async function introspectPostgresCatalog(options) {
                 // (gen_random_uuid(), now()), which Turbine must still synthesize.
                 isGenerated: (typeof row.column_default === 'string' && row.column_default.includes('nextval(')) ||
                     row.is_identity === 'YES',
+                // GENERATED ALWAYS AS (expr) STORED — computed by the database, never
+                // writable. Distinct from isGenerated (serial/identity, which a client
+                // MAY override). is_generated is 'ALWAYS' for STORED columns, else 'NEVER'.
+                isGeneratedStored: row.is_generated === 'ALWAYS',
+                generationExpression: row.is_generated === 'ALWAYS' && row.generation_expression ? row.generation_expression : undefined,
                 isArray,
                 arrayType,
                 pgArrayType: arrayType,
@@ -223,6 +338,20 @@ export async function introspectPostgresCatalog(options) {
                 definition: row.indexdef,
             });
         }
+        // ----- Group check constraints by table -----
+        // pg_get_constraintdef yields e.g. `CHECK ((price >= 0))`; strip the leading
+        // `CHECK ` and the outermost paren pair to recover the raw expression.
+        const checksByTable = new Map();
+        for (const row of checkResult.rows) {
+            if (!tableSet.has(row.table_name))
+                continue;
+            if (!checksByTable.has(row.table_name))
+                checksByTable.set(row.table_name, []);
+            checksByTable.get(row.table_name).push({
+                name: row.conname,
+                expression: stripCheckWrapper(row.definition),
+            });
+        }
         // ----- Collect enums -----
         const enums = {};
         for (const row of enumResult.rows) {
@@ -272,6 +401,13 @@ export async function introspectPostgresCatalog(options) {
                     ? snakeToCamel(fk.sourceColumns[0].replace(/_id$/, ''))
                     : snakeToCamel(fk.constraintName.replace(/^fk_/, '').replace(/_fkey$/, ''))
                 : singularize(snakeToCamel(fk.targetTable));
+            // Referential actions (omit the 'no action' default to keep metadata lean).
+            const actions = fkActions.get(fk.constraintName);
+            const actionFields = {};
+            if (actions?.onDelete && actions.onDelete !== 'no action')
+                actionFields.onDelete = actions.onDelete;
+            if (actions?.onUpdate && actions.onUpdate !== 'no action')
+                actionFields.onUpdate = actions.onUpdate;
             if (!relationsByTable.has(fk.sourceTable))
                 relationsByTable.set(fk.sourceTable, {});
             relationsByTable.get(fk.sourceTable)[belongsToName] = {
@@ -281,6 +417,7 @@ export async function introspectPostgresCatalog(options) {
                 to: fk.targetTable,
                 foreignKey,
                 referenceKey,
+                ...actionFields,
             };
             // --- hasMany on the target (parent) table ---
             // e.g. posts.user_id → users.id creates users.posts (hasMany)
@@ -298,6 +435,7 @@ export async function introspectPostgresCatalog(options) {
                 to: fk.sourceTable,
                 foreignKey,
                 referenceKey,
+                ...actionFields,
             };
         }
         // ----- Conservative many-to-many auto-detection (PURELY ADDITIVE) -----
@@ -415,6 +553,8 @@ export async function introspectPostgresCatalog(options) {
                 uniqueColumns: uniqueByTable.get(tableName) ?? [],
                 relations: relationsByTable.get(tableName) ?? {},
                 indexes: indexesByTable.get(tableName) ?? [],
+                checks: checksByTable.get(tableName) ?? [],
+                ...(viewNameSet.has(tableName) ? { isView: true } : {}),
             };
         }
         return { tables, enums };
@@ -423,3 +563,34 @@ export async function introspectPostgresCatalog(options) {
         await pool.end();
     }
 }
+/**
+ * Recover the raw check expression from `pg_get_constraintdef` output, which
+ * wraps it as `CHECK ((expr))`. Strips the leading `CHECK ` keyword and one
+ * balanced outer paren pair; leaves anything unexpected untouched.
+ */
+export function stripCheckWrapper(def) {
+    let s = def.trim();
+    const m = /^CHECK\s*\((.*)\)$/is.exec(s);
+    if (m)
+        s = m[1].trim();
+    // pg double-wraps single expressions: `(price >= 0)` → unwrap one more pair
+    // only when the parens are balanced across the whole string.
+    if (s.startsWith('(') && s.endsWith(')')) {
+        let depth = 0;
+        let balanced = true;
+        for (let i = 0; i < s.length; i++) {
+            if (s[i] === '(')
+                depth++;
+            else if (s[i] === ')') {
+                depth--;
+                if (depth === 0 && i < s.length - 1) {
+                    balanced = false;
+                    break;
+                }
+            }
+        }
+        if (balanced)
+            s = s.slice(1, -1).trim();
+    }
+    return s;
+}

package/dist/query/batched-loader.d.ts

@@ -47,9 +47,9 @@
  * @module
  */
 import type pg from 'pg';
-import { type SchemaMetadata, type TableMetadata } from '../schema.js';
+import { type RelationDef, type SchemaMetadata, type TableMetadata } from '../schema.js';
 import type { ReselectExecutor } from './builder.js';
-import type { WithClause } from './types.js';
+import type { SkipGlobalFilters, WithClause, WithCount } from './types.js';
 /**
  * A DeferredQuery, minimally typed for what the loader consumes. Kept local to
  * avoid a value import of builder.ts (which imports this module).
@@ -88,6 +88,23 @@ export interface RelationLoadContext {
     inClauseParam: (values: unknown[]) => unknown;
     /** Placeholder for a 1-indexed parameter position (PG: `$n`). */
     paramPlaceholder: (index: number) => string;
+    /**
+     * The query's `skipGlobalFilters` opt-out, threaded onto every child
+     * `buildFindMany` so relation row loads honor (or skip) the target table's
+     * global filter exactly as the join strategy would.
+     */
+    skipGlobalFilters?: SkipGlobalFilters;
+    /**
+     * Render `table`'s global filter against `alias` for a raw follow-up query
+     * (the batched `_count`), numbering its `$n` placeholders AFTER
+     * `precedingParams` already-bound params. Returns `null` when no filter
+     * applies. Provided by the owning QueryInterface so this module needs no
+     * filter machinery of its own.
+     */
+    tableGlobalFilter?: (table: string, alias: string, precedingParams: number) => {
+        clause: string;
+        params: unknown[];
+    } | null;
 }
 /**
  * Adjust a `select`/`omit` pair so that `fields` are guaranteed present in the
@@ -111,6 +128,16 @@ export declare function stripFields(rows: Record<string, unknown>[], fields: str
  * The caller adds these to the base query and strips the added ones afterwards.
  */
 export declare function neededParentKeyFields(parentMeta: TableMetadata, withClause: WithClause): string[];
+/**
+ * Resolve the set of to-many relations a `_count` spec selects. `true` counts
+ * every to-many relation (hasMany + manyToMany) of the table; the record form
+ * counts only the enabled names. Shared by the join builder and the batched
+ * loader so both count the exact same relations.
+ *
+ * Errors: E005 ({@link RelationError}) for an unknown relation name, E003
+ * ({@link ValidationError}) when a named relation is to-one.
+ */
+export declare function resolveCountRelations(parentMeta: TableMetadata, countSpec: WithCount): RelationDef[];
 /**
  * Load every relation in `withClause` for `parents` and attach it onto each row
  * in place. Mirrors the join strategy's output shape exactly. Recurses for nested