@cleverbrush/knex-schema 4.3.1 → 4.4.0

package/dist/migration.d.ts

@@ -95,6 +95,40 @@ export declare function generateMigration(diff: MigrationDiff, tableName: string
  * ```
  */
 export declare function tableExistsInDb(knex: Knex, tableName: string): Promise<boolean>;
+/**
+ * A schema validation issue detected against the live database.
+ */
+export type EntitySchemaValidationIssue = {
+    type: 'missing-table';
+    tableName: string;
+} | {
+    type: 'schema-drift';
+    tableName: string;
+    diff: MigrationDiff;
+};
+/**
+ * Result returned by {@link validateEntitiesAgainstDatabase}.
+ */
+export interface EntitySchemaValidationResult {
+    /** `true` when every entity table exists and has an empty schema diff. */
+    valid: boolean;
+    /** Table names inspected during validation. */
+    checkedTables: string[];
+    /** Missing tables or non-empty schema diffs. */
+    issues: EntitySchemaValidationIssue[];
+}
+/**
+ * Validate entity schemas against a live database without changing anything.
+ *
+ * This is the read-only counterpart to `db push`: it checks every registered
+ * entity table, including class-table-inheritance variant tables, and reports
+ * missing tables or schema drift.
+ *
+ * @param knex - A configured Knex instance or transaction.
+ * @param entities - The entity definitions to validate.
+ * @returns A validation result with all detected issues.
+ */
+export declare function validateEntitiesAgainstDatabase(knex: Knex, entities: Entity<any, any>[]): Promise<EntitySchemaValidationResult>;
 /**
  * Return `true` when a {@link MigrationDiff} has no operations — i.e. the
  * database table is already in sync with the schema.

package/dist/operations/insert.d.ts

@@ -1,11 +1,54 @@
-import type { InferType } from '@cleverbrush/schema';
+import type { InferType, ObjectSchemaBuilder } from '@cleverbrush/schema';
 import type { Knex } from 'knex';
 import type { SchemaQueryBuilder } from '../SchemaQueryBuilder.js';
 import type { ColumnRef, InsertType } from '../types.js';
-export declare class OnConflictBuilder<TLocalSchema extends import('@cleverbrush/schema').ObjectSchemaBuilder<any, any, any, any, any, any, any>, TResult> {
+type AnyObjectSchema = ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+/**
+ * Helpers available to `onConflict().merge()` update expressions and
+ * conditional `where` callbacks.
+ */
+export interface OnConflictMergeHelpers<TLocalSchema extends AnyObjectSchema> {
+    /** The Knex instance used by the query builder. */
+    readonly knex: Knex;
+    /**
+     * Resolve a schema property reference to its mapped database column name.
+     */
+    column(ref: ColumnRef<TLocalSchema>): string;
+    /**
+     * Create a raw SQL expression with Knex bindings.
+     */
+    raw(sql: string, bindings?: readonly unknown[]): Knex.Raw;
+    /**
+     * Reference the `excluded.<column>` value in an upsert merge expression.
+     */
+    excluded(ref: ColumnRef<TLocalSchema>): Knex.Raw;
+}
+/**
+ * Value accepted in explicit `onConflict().merge(data, updateData)` payloads.
+ */
+export type OnConflictUpdateValue<TLocalSchema extends AnyObjectSchema, TValue> = TValue | Knex.Raw | ((helpers: OnConflictMergeHelpers<TLocalSchema>) => TValue | Knex.Raw);
+/**
+ * Explicit update payload accepted by `onConflict().merge()`.
+ */
+export type OnConflictUpdateData<TLocalSchema extends AnyObjectSchema> = Partial<{
+    [K in keyof InferType<TLocalSchema>]: OnConflictUpdateValue<TLocalSchema, InferType<TLocalSchema>[K]>;
+}>;
+/**
+ * Options for `onConflict().merge()`.
+ */
+export interface OnConflictMergeOptions<TLocalSchema extends AnyObjectSchema> {
+    /**
+     * Attach a conditional `WHERE` clause to the generated merge.
+     *
+     * This is useful for row-version or timestamp guarded upserts.
+     */
+    where?: (query: Knex.QueryBuilder, helpers: OnConflictMergeHelpers<TLocalSchema>) => void;
+}
+export declare class OnConflictBuilder<TLocalSchema extends AnyObjectSchema, TResult> {
     #private;
     constructor(knex: Knex, localSchema: TLocalSchema, _parent: SchemaQueryBuilder<TLocalSchema, TResult>, conflictColumns: string[]);
-    merge(data: InsertType<TLocalSchema>, updateData?: Partial<InferType<TLocalSchema>>): Promise<TResult>;
+    merge(data: InsertType<TLocalSchema>, options?: OnConflictMergeOptions<TLocalSchema>): Promise<TResult>;
+    merge(data: InsertType<TLocalSchema>, updateData?: OnConflictUpdateData<TLocalSchema>, options?: OnConflictMergeOptions<TLocalSchema>): Promise<TResult>;
     ignore(data: InsertType<TLocalSchema>): Promise<TResult | undefined>;
 }
 export declare function insertImpl(builder: SchemaQueryBuilder<any, any>, data: InsertType<any>): Promise<any>;
@@ -24,3 +67,4 @@ export declare function bulkUpsertImpl(builder: SchemaQueryBuilder<any, any>, ro
     conflictColumns: ColumnRef<any>[];
     chunkSize?: number;
 }): Promise<any[]>;
+export {};

package/dist/types.d.ts

@@ -89,6 +89,30 @@ export type ValidatedSpec = ({
     type: 'many';
 } & ValidatedJoinManySpec);
 export type InsertType<T extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = InferType<ReturnType<T['makeAllPropsOptional']>>;
+type OptionalKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? K : never;
+}[keyof T];
+type RequiredKeys<T> = Exclude<keyof T, OptionalKeys<T>>;
+/**
+ * Normalize a schema-inferred property type to the value shape commonly
+ * returned by database rows.
+ *
+ * Optional schema properties may be absent in payloads, but database rows use
+ * `NULL` for persisted missing values.
+ */
+export type InferDatabaseValue<T> = undefined extends T ? Exclude<T, undefined> | null | undefined : T;
+/**
+ * Infer the object shape of a persisted database row from an object schema.
+ *
+ * This is useful for mapper code and raw-query helpers where `InferType<T>`
+ * is too strict because optional schema properties can come back as `null`
+ * from SQL.
+ */
+export type InferDatabaseRow<T extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = {
+    [K in RequiredKeys<InferType<T>>]: InferDatabaseValue<InferType<T>[K]>;
+} & {
+    [K in OptionalKeys<InferType<T>>]?: InferDatabaseValue<InferType<T>[K]>;
+};
 import type { COMPOSITE_PRIMARY_KEY_BRAND, PRIMARY_KEY_BRAND } from './extension.js';
 /**
  * Detect whether a property schema is branded as a primary key (i.e. its

package/package.json

@@ -5,7 +5,7 @@
         "email": "andrew_zol@cleverbrush.com"
     },
     "dependencies": {
-        "@cleverbrush/schema": "^4.3.1"
+        "@cleverbrush/schema": "^4.4.0"
     },
     "peerDependencies": {
         "knex": ">=3.1.0"
@@ -52,5 +52,5 @@
     },
     "type": "module",
     "types": "./dist/index.d.ts",
-    "version": "4.3.1"
+    "version": "4.4.0"
 }