tempest-db-js 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1157,6 +1157,11 @@ interface ColumnFlags {
     readonly primaryKey: boolean;
     readonly notNull: boolean;
     readonly hasDefault: boolean;
+    /**
+     * A `UNIQUE` constraint on the column. Does NOT influence the inferred type —
+     * it is DDL-only metadata (mirrors SQLAlchemy's `mapped_column(unique=True)`).
+     */
+    readonly unique: boolean;
 }
 /**
  * The canonical, dialect-neutral kind of a column type. Mirrors SQLAlchemy's
@@ -1218,9 +1223,31 @@ declare const sql: {
     /** Escape hatch: a verbatim SQL expression rendered as-is. */
     readonly raw: (expression: string) => DefaultValue;
 };
+/**
+ * A referential action for a foreign key's `ON DELETE` / `ON UPDATE` clause.
+ * Dialect-neutral tokens rendered uppercase at the DDL edge (mirrors
+ * SQLAlchemy's `ForeignKey(ondelete=..., onupdate=...)`).
+ */
+type FkAction = "cascade" | "restrict" | "set null" | "set default" | "no action";
+/**
+ * A resolved foreign-key reference: the target `table.column` plus optional
+ * referential actions. Produced by `Column.references("table.column", ...)`.
+ */
+interface ForeignKeyRef {
+    readonly table: string;
+    readonly column: string;
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
+}
+/** Options for a foreign-key reference (referential actions). */
+interface ForeignKeyOptions {
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
+}
 /**
  * A typed column builder. Holds runtime metadata (structured `type`, `flags`,
- * `default`, `onUpdate`) and a phantom static type `T` used purely for inference.
+ * `default`, `onUpdate`, foreign-key `reference`) and a phantom static type `T`
+ * used purely for inference.
  */
 declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     readonly type: ColumnType;
@@ -1229,13 +1256,17 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     readonly defaultValue: DefaultValue | null;
     /** The value re-applied on update (e.g. `updated_at`), or `null`. */
     readonly onUpdateValue: DefaultValue | null;
+    /** The foreign-key reference this column points to, or `null` for none. */
+    readonly reference: ForeignKeyRef | null;
     /** Phantom: never read at runtime, only inspected by the type system. */
     readonly [TYPE]: T;
     constructor(type: ColumnType, flags: F, 
     /** The default applied on insert, or `null` for none. */
     defaultValue?: DefaultValue | null, 
     /** The value re-applied on update (e.g. `updated_at`), or `null`. */
-    onUpdateValue?: DefaultValue | null);
+    onUpdateValue?: DefaultValue | null, 
+    /** The foreign-key reference this column points to, or `null` for none. */
+    reference?: ForeignKeyRef | null);
     primaryKey(): Column<T, F & {
         primaryKey: true;
         hasDefault: true;
@@ -1243,6 +1274,24 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     notNull(): Column<T, F & {
         notNull: true;
     }>;
+    /**
+     * Add a `UNIQUE` constraint to the column (mirrors SQLAlchemy's
+     * `mapped_column(unique=True)`). DDL-only — does not change the inferred type.
+     */
+    unique(): Column<T, F & {
+        unique: true;
+    }>;
+    /**
+     * Declare a foreign-key reference to another table's column, à la SQLAlchemy's
+     * `mapped_column(ForeignKey("table.column", ondelete=...))`. DDL-only — does
+     * not change the inferred type.
+     *
+     * @param ref The target as `"table.column"` (e.g. `"users.id"`).
+     * @param options Optional `onDelete` / `onUpdate` referential actions.
+     * @returns A new column carrying the reference.
+     * @throws Error When `ref` is not a valid `"table.column"` string.
+     */
+    references(ref: string, options?: ForeignKeyOptions): Column<T, F>;
     /**
      * Set the insert-time default: a constant value of type `T`, or a portable
      * server-side expression from {@link sql} (e.g. `sql.now()`, `sql.uuidv4()`).
@@ -1322,9 +1371,58 @@ declare const column: {
     /** `ENUM(...values)` → a string-literal union of the given values. */
     readonly enum: <const E extends string>(...values: E[]) => Column<E, ColumnFlags>;
 };
+/**
+ * A table-level constraint declared via a model's `static tableArgs`. Mirrors
+ * SQLAlchemy's `__table_args__` entries (`UniqueConstraint`, `ForeignKeyConstraint`).
+ * Use the {@link unique} and {@link foreignKey} helpers to build these.
+ */
+type TableConstraint = {
+    readonly kind: "unique";
+    readonly name?: string | undefined;
+    readonly columns: readonly string[];
+} | {
+    readonly kind: "foreignKey";
+    readonly name?: string | undefined;
+    readonly columns: readonly string[];
+    readonly refTable: string;
+    readonly refColumns: readonly string[];
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
+};
+/**
+ * Declare a (possibly composite) `UNIQUE` table constraint over the given
+ * columns. Mirrors SQLAlchemy's `UniqueConstraint("a", "b")`.
+ *
+ * @param columns The column names covered by the constraint.
+ * @returns A unique {@link TableConstraint}.
+ * @throws Error When no columns are given.
+ */
+declare function unique(...columns: string[]): TableConstraint;
+/**
+ * Declare a (possibly composite) foreign-key table constraint. Mirrors
+ * SQLAlchemy's `ForeignKeyConstraint([...], [...], ondelete=...)`.
+ *
+ * @param columns The local column names.
+ * @param refTable The referenced table name.
+ * @param refColumns The referenced column names (same length as `columns`).
+ * @param options Optional constraint `name` and referential actions.
+ * @returns A foreign-key {@link TableConstraint}.
+ * @throws Error When the column arrays are empty or mismatched in length.
+ */
+declare function foreignKey(columns: string[], refTable: string, refColumns: string[], options?: {
+    name?: string;
+    onDelete?: FkAction;
+    onUpdate?: FkAction;
+}): TableConstraint;
 /** Base class every model extends, SQLAlchemy-declarative style. */
 declare abstract class Model {
     static tablename: string;
+    /**
+     * Optional table-level constraints (composite unique / foreign keys), returned
+     * by a thunk so forward references resolve lazily. Mirrors SQLAlchemy's
+     * `__table_args__`.
+     */
+    static tableArgs?: () => readonly TableConstraint[];
 }
 /**
  * Reflect a model class into its column map at runtime, keyed by column name.
@@ -1349,6 +1447,7 @@ type ColumnKeys<M> = {
 /** Constructor type for a Model subclass. */
 type ModelClass = (new () => Model) & {
     tablename: string;
+    tableArgs?: () => readonly TableConstraint[];
 };
 /** Flatten an intersection into a single object literal for clean inference. */
 type Simplify<T> = {
@@ -1386,4 +1485,4 @@ type InferInsert<C extends ModelClass> = Simplify<{
     [K in Exclude<ColumnKeys<InstanceType<C>>, OptionalInsertKeys<InstanceType<C>>>]: ColValue<InstanceType<C>[K]>;
 }>;
 
-export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, Model, type ModelClass, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, type OnConflict, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, SqliteDialect, type SyncDriver, SyncEngine, SyncResult, SyncSession, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, activeRecord, and, avg, belongsTo, column, columnsOf, count, createEngine, createSyncEngine, del, detectDialect, fromDict, getDialect, hasMany, insert, isCondition, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, update };
+export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type FkAction, type ForeignKeyOptions, type ForeignKeyRef, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, Model, type ModelClass, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, type OnConflict, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, SqliteDialect, type SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, activeRecord, and, avg, belongsTo, column, columnsOf, count, createEngine, createSyncEngine, del, detectDialect, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, unique, update };

package/dist/index.d.ts

@@ -1157,6 +1157,11 @@ interface ColumnFlags {
     readonly primaryKey: boolean;
     readonly notNull: boolean;
     readonly hasDefault: boolean;
+    /**
+     * A `UNIQUE` constraint on the column. Does NOT influence the inferred type —
+     * it is DDL-only metadata (mirrors SQLAlchemy's `mapped_column(unique=True)`).
+     */
+    readonly unique: boolean;
 }
 /**
  * The canonical, dialect-neutral kind of a column type. Mirrors SQLAlchemy's
@@ -1218,9 +1223,31 @@ declare const sql: {
     /** Escape hatch: a verbatim SQL expression rendered as-is. */
     readonly raw: (expression: string) => DefaultValue;
 };
+/**
+ * A referential action for a foreign key's `ON DELETE` / `ON UPDATE` clause.
+ * Dialect-neutral tokens rendered uppercase at the DDL edge (mirrors
+ * SQLAlchemy's `ForeignKey(ondelete=..., onupdate=...)`).
+ */
+type FkAction = "cascade" | "restrict" | "set null" | "set default" | "no action";
+/**
+ * A resolved foreign-key reference: the target `table.column` plus optional
+ * referential actions. Produced by `Column.references("table.column", ...)`.
+ */
+interface ForeignKeyRef {
+    readonly table: string;
+    readonly column: string;
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
+}
+/** Options for a foreign-key reference (referential actions). */
+interface ForeignKeyOptions {
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
+}
 /**
  * A typed column builder. Holds runtime metadata (structured `type`, `flags`,
- * `default`, `onUpdate`) and a phantom static type `T` used purely for inference.
+ * `default`, `onUpdate`, foreign-key `reference`) and a phantom static type `T`
+ * used purely for inference.
  */
 declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     readonly type: ColumnType;
@@ -1229,13 +1256,17 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     readonly defaultValue: DefaultValue | null;
     /** The value re-applied on update (e.g. `updated_at`), or `null`. */
     readonly onUpdateValue: DefaultValue | null;
+    /** The foreign-key reference this column points to, or `null` for none. */
+    readonly reference: ForeignKeyRef | null;
     /** Phantom: never read at runtime, only inspected by the type system. */
     readonly [TYPE]: T;
     constructor(type: ColumnType, flags: F, 
     /** The default applied on insert, or `null` for none. */
     defaultValue?: DefaultValue | null, 
     /** The value re-applied on update (e.g. `updated_at`), or `null`. */
-    onUpdateValue?: DefaultValue | null);
+    onUpdateValue?: DefaultValue | null, 
+    /** The foreign-key reference this column points to, or `null` for none. */
+    reference?: ForeignKeyRef | null);
     primaryKey(): Column<T, F & {
         primaryKey: true;
         hasDefault: true;
@@ -1243,6 +1274,24 @@ declare class Column<T, F extends ColumnFlags = ColumnFlags> {
     notNull(): Column<T, F & {
         notNull: true;
     }>;
+    /**
+     * Add a `UNIQUE` constraint to the column (mirrors SQLAlchemy's
+     * `mapped_column(unique=True)`). DDL-only — does not change the inferred type.
+     */
+    unique(): Column<T, F & {
+        unique: true;
+    }>;
+    /**
+     * Declare a foreign-key reference to another table's column, à la SQLAlchemy's
+     * `mapped_column(ForeignKey("table.column", ondelete=...))`. DDL-only — does
+     * not change the inferred type.
+     *
+     * @param ref The target as `"table.column"` (e.g. `"users.id"`).
+     * @param options Optional `onDelete` / `onUpdate` referential actions.
+     * @returns A new column carrying the reference.
+     * @throws Error When `ref` is not a valid `"table.column"` string.
+     */
+    references(ref: string, options?: ForeignKeyOptions): Column<T, F>;
     /**
      * Set the insert-time default: a constant value of type `T`, or a portable
      * server-side expression from {@link sql} (e.g. `sql.now()`, `sql.uuidv4()`).
@@ -1322,9 +1371,58 @@ declare const column: {
     /** `ENUM(...values)` → a string-literal union of the given values. */
     readonly enum: <const E extends string>(...values: E[]) => Column<E, ColumnFlags>;
 };
+/**
+ * A table-level constraint declared via a model's `static tableArgs`. Mirrors
+ * SQLAlchemy's `__table_args__` entries (`UniqueConstraint`, `ForeignKeyConstraint`).
+ * Use the {@link unique} and {@link foreignKey} helpers to build these.
+ */
+type TableConstraint = {
+    readonly kind: "unique";
+    readonly name?: string | undefined;
+    readonly columns: readonly string[];
+} | {
+    readonly kind: "foreignKey";
+    readonly name?: string | undefined;
+    readonly columns: readonly string[];
+    readonly refTable: string;
+    readonly refColumns: readonly string[];
+    readonly onDelete?: FkAction | undefined;
+    readonly onUpdate?: FkAction | undefined;
+};
+/**
+ * Declare a (possibly composite) `UNIQUE` table constraint over the given
+ * columns. Mirrors SQLAlchemy's `UniqueConstraint("a", "b")`.
+ *
+ * @param columns The column names covered by the constraint.
+ * @returns A unique {@link TableConstraint}.
+ * @throws Error When no columns are given.
+ */
+declare function unique(...columns: string[]): TableConstraint;
+/**
+ * Declare a (possibly composite) foreign-key table constraint. Mirrors
+ * SQLAlchemy's `ForeignKeyConstraint([...], [...], ondelete=...)`.
+ *
+ * @param columns The local column names.
+ * @param refTable The referenced table name.
+ * @param refColumns The referenced column names (same length as `columns`).
+ * @param options Optional constraint `name` and referential actions.
+ * @returns A foreign-key {@link TableConstraint}.
+ * @throws Error When the column arrays are empty or mismatched in length.
+ */
+declare function foreignKey(columns: string[], refTable: string, refColumns: string[], options?: {
+    name?: string;
+    onDelete?: FkAction;
+    onUpdate?: FkAction;
+}): TableConstraint;
 /** Base class every model extends, SQLAlchemy-declarative style. */
 declare abstract class Model {
     static tablename: string;
+    /**
+     * Optional table-level constraints (composite unique / foreign keys), returned
+     * by a thunk so forward references resolve lazily. Mirrors SQLAlchemy's
+     * `__table_args__`.
+     */
+    static tableArgs?: () => readonly TableConstraint[];
 }
 /**
  * Reflect a model class into its column map at runtime, keyed by column name.
@@ -1349,6 +1447,7 @@ type ColumnKeys<M> = {
 /** Constructor type for a Model subclass. */
 type ModelClass = (new () => Model) & {
     tablename: string;
+    tableArgs?: () => readonly TableConstraint[];
 };
 /** Flatten an intersection into a single object literal for clean inference. */
 type Simplify<T> = {
@@ -1386,4 +1485,4 @@ type InferInsert<C extends ModelClass> = Simplify<{
     [K in Exclude<ColumnKeys<InstanceType<C>>, OptionalInsertKeys<InstanceType<C>>>]: ColValue<InstanceType<C>[K]>;
 }>;
 
-export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, Model, type ModelClass, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, type OnConflict, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, SqliteDialect, type SyncDriver, SyncEngine, SyncResult, SyncSession, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, activeRecord, and, avg, belongsTo, column, columnsOf, count, createEngine, createSyncEngine, del, detectDialect, fromDict, getDialect, hasMany, insert, isCondition, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, update };
+export { ActiveRecord, type ActiveRecordManager, Agg, type AggregateTerm, type AsyncDriver, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, type BelongsTo, type ColRef, type ColType, Column, type ColumnFlags, type ColumnType, type ColumnTypeKind, type ColumnTypeMeta, type CompiledQuery, type CondNode, type Condition, type DefaultValue, DeleteBuilder, type DeleteNode, type Dialect, type DriverResult, type EngineOptions, type Executable, type FkAction, type ForeignKeyOptions, type ForeignKeyRef, type HasMany, type InferInsert, type InferModel, InsertBuilder, type InsertNode, InvalidDatabaseUrl, JoinBuilder, type JoinClause, type JoinNode, type JoinOn, type JoinSelection, type JoinWhereInput, Model, type ModelClass, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, type OnConflict, type Operator, type OperatorsFor, type OrderTerm, type PaginationFilter, type PaginationResult, type ParsedDatabaseUrl, type PoolOptions, type PortableExpression, PostgresDialect, QueryExecutionError, type QueryLogger, type QueryNode, RecordNotFound, type Relation, type RelationValue, type ReservedAsyncDriver, type Returning, type RowOf, SelectBuilder, type SelectNode, type SortDirection, type Sources, SqliteDialect, type SyncDriver, SyncEngine, SyncResult, SyncSession, type TableConstraint, UpdateBuilder, type UpdateNode, ValidationError, type WhereArg, type WhereInput, type WithRelations, activeRecord, and, avg, belongsTo, column, columnsOf, count, createEngine, createSyncEngine, del, detectDialect, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, unique, update };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { ActiveRecord, Agg, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, Column, DeleteBuilder, InsertBuilder, InvalidDatabaseUrl, JoinBuilder, Model, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, PostgresDialect, QueryExecutionError, RecordNotFound, SelectBuilder, SqliteDialect, SyncEngine, SyncResult, SyncSession, UpdateBuilder, ValidationError, activeRecord, and, avg, belongsTo, column, columnsOf, count, createEngine, createSyncEngine, del, detectDialect, fromDict, getDialect, hasMany, insert, isCondition, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, update } from './chunk-Q32CBI2A.js';
+export { ActiveRecord, Agg, AsyncEngine, AsyncResult, AsyncSession, BaseDialect, BaseRepository, Column, DeleteBuilder, InsertBuilder, InvalidDatabaseUrl, JoinBuilder, Model, MysqlDialect, NoResultError, NodeSqliteDriver, OPERATORS, PostgresDialect, QueryExecutionError, RecordNotFound, SelectBuilder, SqliteDialect, SyncEngine, SyncResult, SyncSession, UpdateBuilder, ValidationError, activeRecord, and, avg, belongsTo, column, columnsOf, count, createEngine, createSyncEngine, del, detectDialect, foreignKey, fromDict, getDialect, hasMany, insert, isCondition, join, loadRelations, max, min, not, or, parse, parseDatabaseUrl, select, sql, stringify, sum, toCondNode, toDict, toJSON, unique, update } from './chunk-JR4MLFQN.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map