uql-orm 0.41.0 → 0.41.1

package/dist/entity/decorator/members.d.ts

@@ -7,11 +7,29 @@ type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext
  * primary key's own type. Which is what makes `@Field({ references: () => User })` on a `number`, where
  * `User.id` is a `uuid`, a compile error rather than a column that disagrees with its property.
  */
+/**
+ * The value type the options declare, which the decorated property is then checked against.
+ *
+ * `enum` narrows it to its own values, so the property must spell out the same set. Only the values
+ * the declared `type` admits count, which is what keeps `enum: [2]` off a `String` field.
+ */
 type DeclaredValue<O> = O extends {
     readonly type: infer T extends FieldType;
-} ? TsTypeOf<T> : O extends {
+} ? O extends {
+    readonly enum: infer E extends readonly unknown[];
+} ? EnumValue<Extract<E[number], TsTypeOf<T>>, TsTypeOf<T>> : TsTypeOf<T> : O extends {
     readonly references: EntityGetter<infer E>;
 } ? IdValue<E> : never;
+/**
+ * The enum's members, or a named complaint when they widened.
+ *
+ * `['a', 'b']` without `as const` infers `string[]`, whose member type is the field's own type and
+ * so narrows nothing - the check would be silently off. Resolving to a type no property can hold
+ * makes that a compile error that says why, rather than a decoration.
+ */
+type EnumValue<Members, Declared> = Declared extends Members ? {
+    readonly __enumNeedsAsConst: true;
+} : Members;
 /**
  * Declares a persisted field.
  *

package/dist/entity/metadata/definition.js

@@ -1,5 +1,5 @@
 import { SOFT_DELETE_FILTER } from '../../type/index.js';
-import { getKeys, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, normalizeIndexWhere, upperFirst, } from '../../util/index.js';
+import { getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
 // Held on `globalThis` via the global symbol registry so a single metadata map survives multiple
 // evaluations of this module (HMR, duplicated/federated bundles, ESM+CJS dual-loading). Version-suffixed
@@ -66,7 +66,7 @@ export function defineIndex(entity, index) {
     meta.indexes.push({
         ...index,
         unique: index.unique ?? false,
-        where: normalizeIndexWhere(index.where),
+        where: ddlText(index.where, 'a partial-index predicate'),
         columns: index.columns.map(normalizeIndexColumn),
     });
     return meta;
@@ -124,6 +124,10 @@ export function defineEntity(entity, opts = {}) {
     // after class decorators return; draining empties the bag, so whichever runs second is a no-op.
     applyMembers(entity, ownRegistrations(entity));
     applyMembers(entity, opts);
+    // Unnamed checks are named by the generator, as unnamed indexes are.
+    for (const check of opts.checks ?? []) {
+        (meta.checks ??= []).push({ name: check.name, expression: ddlText(check.expression, 'a check constraint') });
+    }
     for (const index of opts.indexes ?? []) {
         defineIndex(entity, index);
     }

package/dist/migrate/builder/migrationBuilder.js

@@ -5,7 +5,7 @@
  * - OperationRecorder: Record operations only (for code generation)
  * - MigrationBuilder: Execute DDL operations (for integration tests/runtime)
  */
-import { normalizeIndexColumn, normalizeIndexWhere } from '../../util/index.js';
+import { ddlText, normalizeIndexColumn } from '../../util/index.js';
 import { derivedIndexName } from '../../util/sql.util.js';
 import { createSchemaGenerator } from '../schemaGenerator.js';
 import { splitSqlStatements } from './splitSqlStatements.js';
@@ -29,7 +29,7 @@ function createIndexOperation(tableName, columns, options = {}) {
             ...index,
             name: name ??
                 derivedIndexName(tableName, entries.map((entry) => entry.column)),
-            where: normalizeIndexWhere(index.where),
+            where: ddlText(index.where, 'a partial-index predicate'),
             entries,
             unique: unique ?? false,
         },

package/dist/migrate/builder/tableBuilder.js

@@ -3,7 +3,7 @@
  *
  * Fluent API for defining tables in migrations.
  */
-import { normalizeIndexColumn, normalizeIndexWhere } from '../../util/index.js';
+import { ddlText, normalizeIndexColumn } from '../../util/index.js';
 import { derivedIndexName } from '../../util/sql.util.js';
 import { ColumnBuilder } from './columnBuilder.js';
 import { expr } from './expressions.js';
@@ -171,7 +171,7 @@ export class TableBuilder {
         this._indexes.push({
             ...rest,
             name: name ?? `${prefix}_${this._name}_${entries.map((entry) => entry.column).join('_')}`,
-            where: normalizeIndexWhere(rest.where),
+            where: ddlText(rest.where, 'a partial-index predicate'),
             entries,
             unique,
         });

package/dist/migrate/schemaGenerator.js

@@ -3,7 +3,7 @@ import { getMeta } from '../entity/index.js';
 import { areTypesEqual, canonicalToSql, fieldOptionsToCanonical, isVectorCategory, sqlToCanonical, } from '../schema/canonicalType.js';
 import { buildSchemaAST } from '../schema/schemaASTBuilder.js';
 import { getKeys, isAutoIncrement, qualifyName } from '../util/index.js';
-import { derivedForeignKeyName } from '../util/sql.util.js';
+import { derivedCheckName, derivedForeignKeyName } from '../util/sql.util.js';
 import { formatDefaultValue, SqlExpression } from './builder/expressions.js';
 import { indexDdlFor } from './ddl/index.js';
 import { fullColumnDefinitionToNode, tableDefinitionToNode } from './generator/definitionToNode.js';
@@ -247,6 +247,10 @@ export class SqlSchemaGenerator {
         if (column.isUnique && !column.isPrimaryKey) {
             def += ' UNIQUE';
         }
+        if (column.enum?.length) {
+            const values = column.enum.map((value) => this.dialect.escape(value)).join(', ');
+            def += ` CHECK (${this.escapeId(column.name)} IN (${values}))`;
+        }
         def += this.defaultClause(column);
         if (column.comment) {
             def += this.generateColumnComment(column.name, column.comment);
@@ -493,6 +497,10 @@ export class SqlSchemaGenerator {
             const pkCols = table.primaryKey.map((c) => this.escapeId(c.name)).join(', ');
             constraints.push(`PRIMARY KEY (${pkCols})`);
         }
+        (table.checks ?? []).forEach((check, i) => {
+            const name = check.name ?? derivedCheckName(table.name, i + 1);
+            constraints.push(`CONSTRAINT ${this.escapeId(name)} CHECK (${check.expression})`);
+        });
         for (const rel of table.outgoingRelations) {
             if (rel.from.columns.length > 0) {
                 const fromCols = rel.from.columns.map((c) => this.escapeId(c.name)).join(', ');

package/dist/schema/schemaAST.js

@@ -19,6 +19,7 @@ export function createTableNode(name, schema, comment) {
         columns: new Map(),
         primaryKey: [],
         indexes: [],
+        checks: [],
         incomingRelations: [],
         outgoingRelations: [],
     };

package/dist/schema/schemaASTBuilder.js

@@ -71,6 +71,7 @@ function addTableFromEntity(ctx, meta) {
     const tableName = ctx.resolveTableName(meta);
     const table = createTableNode(tableName, ctx.resolveSchema(meta));
     const { columns, primaryKey } = table;
+    table.checks?.push(...(meta.checks ?? []));
     // Add columns from fields
     const fields = meta.fields;
     for (const key of Object.keys(fields)) {
@@ -94,6 +95,7 @@ function addTableFromEntity(ctx, meta) {
             isAutoIncrement: field.autoIncrement ?? (isPrimaryKey && type.category === 'integer'),
             isUnique: field.unique ?? false,
             comment: field.comment,
+            enum: field.enum,
             table,
             referencedBy: [],
             references: undefined,

package/dist/schema/types.d.ts

@@ -40,6 +40,26 @@ export interface CanonicalType {
  * Actions for foreign key ON DELETE and ON UPDATE clauses.
  */
 export type ForeignKeyAction = 'CASCADE' | 'SET NULL' | 'SET DEFAULT' | 'RESTRICT' | 'NO ACTION';
+/**
+ * The values a column accepts, rendered as `CHECK (col IN (...))`.
+ *
+ * Strings and numbers only: those are what `IN (...)` can state, and each is escaped by the
+ * dialect's own literal rules, so a number stays bare where a string is quoted.
+ */
+export type EnumValues = readonly (string | number)[];
+/**
+ * A `CHECK` constraint as the schema holds it, its expression already text. Declared here rather
+ * than beside the entity types because a table node also comes from introspection, where there is
+ * no entity to have authored one.
+ *
+ * Only ever compared by presence, never by content: a check is SQL text, and a database reprints
+ * text from its parse tree, so `CHECK ("balance" >= 0)` reads back as `CHECK ((balance >= (0)::numeric))`.
+ */
+export interface CheckSchema {
+    /** Absent when nothing named it, which the generator fills in with `derivedCheckName`. */
+    readonly name?: string;
+    readonly expression: string;
+}
 /**
  * Default action for foreign key ON DELETE and ON UPDATE clauses.
  */
@@ -84,6 +104,8 @@ export interface ColumnNode {
     readonly isAutoIncrement: boolean;
     /** Whether this column has a unique constraint */
     readonly isUnique: boolean;
+    /** The values the column accepts. See {@link EnumValues}. */
+    readonly enum?: EnumValues;
     /** Column comment/description */
     readonly comment?: string;
     /** Reference to the parent table */
@@ -115,6 +137,8 @@ export interface TableNode {
     readonly primaryKey: ColumnNode[];
     /** Indexes on this table */
     readonly indexes: IndexNode[];
+    /** `CHECK` constraints on this table. Optional: a node can be built without ever naming one. */
+    readonly checks?: CheckSchema[];
     /** Optional table comment */
     readonly comment?: string;
     /** Relationships pointing TO this table (other tables referencing this one) */

package/dist/type/entity.d.ts

@@ -1,4 +1,4 @@
-import type { ForeignKeyAction, IndexType } from '../schema/types.js';
+import type { CheckSchema, EnumValues, ForeignKeyAction, IndexType } from '../schema/types.js';
 import type { FilterOptions } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { Except, IsMany, Json, Scalar, Type, Unpacked } from './utility.js';
@@ -292,6 +292,20 @@ export type FieldOptions<V = TsTypeOf<FieldType>> = {
      * @example `@Field({ references: () => Company, onDelete: 'CASCADE' }) companyId?: string;`
      */
     readonly onDelete?: ForeignKeyAction;
+    /**
+     * The values the column accepts, enforced by the database as well as by TypeScript.
+     *
+     * Emitted as a column `CHECK (col IN (...))` on every SQL dialect rather than a native enum type:
+     * one code path, no separate schema object to order, and adding a value stays an ordinary column
+     * change instead of Postgres's irreversible `ALTER TYPE ... ADD VALUE`.
+     *
+     * Not constrained against the field's own type here: the decorator narrows the property to these
+     * values instead, which reports a mismatch where the mistake is rather than as an unrelated
+     * `never`. `as const` is what makes them literal, and so what makes any of it check.
+     *
+     * @example `@Field({ type: String, enum: ['draft', 'paid'] as const })`
+     */
+    readonly enum?: EnumValues;
     readonly virtual?: QueryRaw;
     readonly updatable?: boolean;
     readonly eager?: boolean;
@@ -699,6 +713,8 @@ export type EntityMeta<E> = {
     };
     /** Composite indexes defined via @Index decorator */
     indexes?: EntityIndexMeta[];
+    /** `CHECK` constraints, their expressions already reduced to text. */
+    checks?: CheckSchema[];
     /** Lifecycle hooks registered via @BeforeInsert, @AfterUpdate, etc. */
     hooks?: Partial<Record<HookEvent, HookRegistration[]>>;
     processed?: boolean;
@@ -709,6 +725,15 @@ export type EntityMeta<E> = {
  * Optional `fields`, `relations`, `indexes`, and `hooks` register metadata in one call for
  * decorator-free setups. Omit them when using `@Field` / `@ManyToOne` / etc.
  */
+/**
+ * A table-level `CHECK`. The expression is `raw` with no interpolation, like an index expression:
+ * this is DDL, so there is no placeholder a bound value could go into.
+ */
+export type CheckOptions = {
+    /** Derived from the table and the constraint's position when absent. */
+    readonly name?: string;
+    readonly expression: QueryRaw;
+};
 export type EntityOptions<E = unknown> = {
     readonly name?: string;
     /**
@@ -726,6 +751,8 @@ export type EntityOptions<E = unknown> = {
         readonly [K in RelationKey<E>]?: RelationOptionsFor<E[K]>;
     };
     readonly indexes?: readonly EntityIndexInput<FieldKey<E>, E>[];
+    /** Table-level `CHECK` constraints. See {@link CheckOptions}. */
+    readonly checks?: readonly CheckOptions[];
     /** Map hook events to method names on the entity class. */
     readonly hooks?: Partial<Record<HookEvent, readonly MethodKey<E>[]>>;
 };

package/dist/util/ddlExpression.util.d.ts

@@ -0,0 +1,15 @@
+import { type IndexColumnInput, type IndexColumnSchema, QueryRaw } from '../type/index.js';
+/**
+ * SQL bound for DDL, as the text a generator renders. `raw` with no interpolation, or a bare string
+ * where one is still accepted: DDL is evaluated once at creation time, so there is no query context
+ * for the callback form and no placeholder a `CREATE` statement could bind a value into.
+ *
+ * `what` names the thing being declared, so the error says which one the caller got wrong.
+ */
+export declare function ddlText(value: string | QueryRaw, what: string): string;
+export declare function ddlText(value: string | QueryRaw | undefined, what: string): string | undefined;
+/**
+ * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
+ * name, an expression, or an options object - reach the dialects as one.
+ */
+export declare function normalizeIndexColumn(entry: IndexColumnInput): IndexColumnSchema;

package/dist/util/ddlExpression.util.js

@@ -0,0 +1,27 @@
+import { QueryRaw, RAW_VALUE } from '../type/index.js';
+export function ddlText(value, what) {
+    if (!(value instanceof QueryRaw)) {
+        return value;
+    }
+    const sql = value[RAW_VALUE];
+    if (typeof sql !== 'string') {
+        throw new TypeError(`${what} needs raw() with no interpolation, not a function or a bound value`);
+    }
+    return sql;
+}
+/**
+ * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
+ * name, an expression, or an options object - reach the dialects as one.
+ */
+export function normalizeIndexColumn(entry) {
+    if (typeof entry === 'string') {
+        return { column: entry };
+    }
+    if (entry instanceof QueryRaw) {
+        return { column: ddlText(entry, 'an index expression'), expression: true };
+    }
+    const { column, ...rest } = entry;
+    return column instanceof QueryRaw
+        ? { ...rest, column: ddlText(column, 'an index expression'), expression: true }
+        : { ...rest, column };
+}

package/dist/util/index.d.ts

@@ -2,7 +2,7 @@ export * from './dialect.util.js';
 export * from './field.util.js';
 export * from './filters.util.js';
 export * from './hook.util.js';
-export * from './indexColumn.util.js';
+export * from './ddlExpression.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';

package/dist/util/index.js

@@ -2,7 +2,7 @@ export * from './dialect.util.js';
 export * from './field.util.js';
 export * from './filters.util.js';
 export * from './hook.util.js';
-export * from './indexColumn.util.js';
+export * from './ddlExpression.util.js';
 export * from './logger.js';
 export * from './object.util.js';
 export * from './raw.js';

package/dist/util/sql.util.d.ts

@@ -24,6 +24,8 @@ export declare function qualifyName(name: string, schema?: string): string;
  * `table` is the table's own name, never qualified - the result is a single identifier.
  */
 export declare function derivedIndexName(table: string, columns: readonly string[]): string;
+/** The constraint name a check gets when nothing named it: `ck_Order_1`, by declaration order. */
+export declare function derivedCheckName(table: string, position: number): string;
 /** The constraint name a foreign key gets when nothing named it: `fk_Order_customerId`. */
 export declare function derivedForeignKeyName(table: string, columns: readonly string[]): string;
 /**

package/dist/util/sql.util.js

@@ -67,6 +67,10 @@ export function qualifyName(name, schema) {
 export function derivedIndexName(table, columns) {
     return `idx_${table}_${columns.join('_')}`;
 }
+/** The constraint name a check gets when nothing named it: `ck_Order_1`, by declaration order. */
+export function derivedCheckName(table, position) {
+    return `ck_${table}_${position}`;
+}
 /** The constraint name a foreign key gets when nothing named it: `fk_Order_customerId`. */
 export function derivedForeignKeyName(table, columns) {
     return `fk_${table}_${columns.join('_')}`;

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "JSON-native ORM for Node.js, Bun and Deno. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.41.0",
+  "version": "0.41.1",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -56,7 +56,7 @@
     "README.md"
   ],
   "scripts": {
-    "prepack": "bun run verify-dist.ts && cp ../../README.md .",
+    "prepack": "bun run build && bun run verify-dist.ts && cp ../../README.md .",
     "postpack": "rm README.md && npm pkg delete gitHead",
     "compile.browser": "bun build src/browser/index.ts --minify --sourcemap=linked --format=esm --target=browser --outdir=dist/browser --entry-naming 'uql-browser.min.[ext]'",
     "build": "bun run clean && tsc -b tsconfig.build.json && bun run compile.browser && bun run verify-dist.ts",

package/dist/util/indexColumn.util.d.ts

@@ -1,8 +0,0 @@
-import { type IndexColumnInput, type IndexColumnSchema, QueryRaw } from '../type/index.js';
-/**
- * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
- * name, `raw(expression)`, or an options object - reach the dialects as one.
- */
-export declare function normalizeIndexColumn(entry: IndexColumnInput): IndexColumnSchema;
-/** The partial-index predicate, as authored: `raw` for new code, a bare string for old. */
-export declare function normalizeIndexWhere(where: string | QueryRaw | undefined): string | undefined;

package/dist/util/indexColumn.util.js

@@ -1,30 +0,0 @@
-import { QueryRaw, RAW_VALUE } from '../type/index.js';
-/**
- * Reduces an authored index entry to its normalized form, so the three shapes users write - a column
- * name, `raw(expression)`, or an options object - reach the dialects as one.
- */
-export function normalizeIndexColumn(entry) {
-    if (typeof entry === 'string') {
-        return { column: entry };
-    }
-    if (entry instanceof QueryRaw) {
-        return { column: rawSql(entry), expression: true };
-    }
-    const { column, ...rest } = entry;
-    return column instanceof QueryRaw ? { ...rest, column: rawSql(column), expression: true } : { ...rest, column };
-}
-/** The partial-index predicate, as authored: `raw` for new code, a bare string for old. */
-export function normalizeIndexWhere(where) {
-    return where instanceof QueryRaw ? rawSql(where, 'a partial-index predicate') : where;
-}
-/**
- * Index DDL is evaluated once at creation time, so it cannot take the dialect-aware callback form of
- * `raw()` - there is no query context to hand it, and no placeholder a `CREATE INDEX` could bind.
- */
-function rawSql(value, what = 'an index expression') {
-    const sql = value[RAW_VALUE];
-    if (typeof sql !== 'string') {
-        throw new TypeError(`${what} needs raw() with no interpolation, not a function or a bound value`);
-    }
-    return sql;
-}