@cleverbrush/knex-schema 3.1.0 → 4.1.0

package/dist/migration.d.ts

@@ -0,0 +1,160 @@
+import type { ObjectSchemaBuilder } from '@cleverbrush/schema';
+import type { Knex } from 'knex';
+import type { Entity } from './entity.js';
+import type { DatabaseTableState, MigrationDiff, SchemaSnapshot } from './types.js';
+/**
+ * Introspect a PostgreSQL table and return its current state.
+ *
+ * Queries `information_schema.columns`, `pg_indexes`, `pg_constraint`, and
+ * referential constraint metadata to build a complete picture of the table's
+ * columns, indexes, foreign keys, and check constraints.
+ *
+ * @param knex - A configured Knex instance connected to a PostgreSQL database.
+ * @param tableName - The table name to introspect.
+ * @returns The current database state for the table.
+ *
+ * @example
+ * ```ts
+ * const dbState = await introspectDatabase(knex, 'users');
+ * console.log(dbState.columns); // { id: { type: 'integer', ... }, ... }
+ * ```
+ */
+export declare function introspectDatabase(knex: Knex, tableName: string): Promise<DatabaseTableState>;
+/**
+ * Derive a {@link DatabaseTableState} from a code-first `ObjectSchemaBuilder`
+ * without connecting to the database.
+ *
+ * The result mirrors what {@link introspectDatabase} would return after the
+ * schema has been fully applied, so it can be fed directly into
+ * {@link diffSchema} as the `dbState` argument.  This is the foundation of
+ * snapshot-based migration generation.
+ *
+ * @param schema - An `ObjectSchemaBuilder` with DDL extensions.
+ * @returns A {@link DatabaseTableState} representing the schema's ideal DB shape.
+ *
+ * @example
+ * ```ts
+ * const state = entitySchemaToTableState(UserSchema);
+ * // state.columns, state.foreignKeys, state.indexes …
+ * ```
+ */
+export declare function entitySchemaToTableState(schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>): DatabaseTableState;
+/**
+ * Compare a code-first schema model against a live database table state and
+ * produce a diff describing the changes needed to bring the database in sync.
+ *
+ * @param schema - The code-first `ObjectSchemaBuilder`.
+ * @param dbState - The current database state from {@link introspectDatabase}.
+ * @returns A {@link MigrationDiff} describing columns, indexes, and foreign
+ *   keys to add, drop, or alter.
+ *
+ * @example
+ * ```ts
+ * const dbState = await introspectDatabase(knex, 'users');
+ * const diff = diffSchema(UserSchema, dbState);
+ * if (diff.addColumns.length > 0) {
+ *     const migration = generateMigration(diff, 'users');
+ *     console.log(migration.up);
+ * }
+ * ```
+ */
+export declare function diffSchema(schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>, dbState: DatabaseTableState): MigrationDiff;
+/**
+ * Generate migration `up` and `down` code strings from a {@link MigrationDiff}.
+ *
+ * The generated code is valid TypeScript that uses Knex's schema builder API.
+ * Write it to a migration file and run via Knex's migration system.
+ *
+ * @param diff - The schema diff from {@link diffSchema}.
+ * @param tableName - The table name to alter.
+ * @returns An object with `up` and `down` migration code strings.
+ *
+ * @example
+ * ```ts
+ * const diff = diffSchema(UserSchema, dbState);
+ * const migration = generateMigration(diff, 'users');
+ * fs.writeFileSync('migration.ts', migration.full);
+ * ```
+ */
+export declare function generateMigration(diff: MigrationDiff, tableName: string): {
+    up: string;
+    down: string;
+    full: string;
+};
+/**
+ * Check whether a table exists in the connected PostgreSQL database.
+ *
+ * @param knex - A configured Knex instance (or transaction).
+ * @param tableName - The table name to check.
+ * @returns `true` when the table exists.
+ *
+ * @example
+ * ```ts
+ * const exists = await tableExistsInDb(knex, 'users');
+ * if (!exists) await generateCreateTable(UserSchema)(knex);
+ * ```
+ */
+export declare function tableExistsInDb(knex: Knex, tableName: string): Promise<boolean>;
+/**
+ * Return `true` when a {@link MigrationDiff} has no operations — i.e. the
+ * database table is already in sync with the schema.
+ */
+export declare function isDiffEmpty(diff: MigrationDiff): boolean;
+/**
+ * Execute a {@link MigrationDiff} directly against a live database without
+ * writing a migration file. Intended for `db push` (dev-only schema sync).
+ *
+ * Foreign-key constraint drops are executed as raw `ALTER TABLE … DROP
+ * CONSTRAINT` statements before the main `alterTable` call.
+ *
+ * @param knex - A configured Knex instance or transaction.
+ * @param diff - The diff from {@link diffSchema}.
+ * @param tableName - The table to alter.
+ *
+ * @example
+ * ```ts
+ * const dbState = await introspectDatabase(knex, 'users');
+ * const diff = diffSchema(UserSchema, dbState);
+ * if (!isDiffEmpty(diff)) await applyDiff(knex, diff, 'users');
+ * ```
+ */
+export declare function applyDiff(knex: Knex, diff: MigrationDiff, tableName: string): Promise<void>;
+/**
+ * Generate a single combined migration (up + down) for a set of entities by
+ * diffing the current code-first schemas against a **serialized snapshot**
+ * stored in the repository — no live database connection required.
+ *
+ * For each entity's table the function:
+ * - **New tables** (in entities but not in `prevSnapshot`): emits `CREATE TABLE`.
+ * - **Existing tables** (in both): diffs entity schema against the snapshot
+ *   state via {@link diffSchema} and emits `ALTER TABLE` when changes exist.
+ * - **Dropped tables** (in `prevSnapshot` but not in entities): emits
+ *   `DROP TABLE` with a best-effort `CREATE TABLE` in the `down` direction.
+ * - Orders tables topologically by FK dependencies so parent tables are
+ *   created before child tables in `up` (and dropped after in `down`).
+ *
+ * @param entities - The entities from your {@link EntityMap}.
+ * @param prevSnapshot - The last committed {@link SchemaSnapshot} (empty on first run).
+ * @returns `{ up, down, full, isEmpty, nextSnapshot }` where `nextSnapshot`
+ *   should be written to disk after the migration file is created.
+ *
+ * @example
+ * ```ts
+ * const prev = loadSnapshot('./migrations/snapshot.json');
+ * const result = generateMigrationsForContext(
+ *     Object.values({ todos: TodoEntity, users: UserEntity }),
+ *     prev
+ * );
+ * if (!result.isEmpty) {
+ *     fs.writeFileSync('migrations/20260423000000_init.ts', result.full);
+ *     writeSnapshot('./migrations/snapshot.json', result.nextSnapshot);
+ * }
+ * ```
+ */
+export declare function generateMigrationsForContext(entities: Entity<any, any>[], prevSnapshot: SchemaSnapshot): {
+    up: string;
+    down: string;
+    full: string;
+    isEmpty: boolean;
+    nextSnapshot: SchemaSnapshot;
+};

package/dist/operations/delete.d.ts

@@ -0,0 +1,6 @@
+import type { SchemaQueryBuilder } from '../SchemaQueryBuilder.js';
+export declare function deleteImpl(builder: SchemaQueryBuilder<any, any>): Promise<number>;
+export declare function withDeletedImpl(builder: SchemaQueryBuilder<any, any>): any;
+export declare function onlyDeletedImpl(builder: SchemaQueryBuilder<any, any>): any;
+export declare function hardDeleteImpl(builder: SchemaQueryBuilder<any, any>): Promise<number>;
+export declare function restoreImpl(builder: SchemaQueryBuilder<any, any>): Promise<any[]>;

package/dist/operations/helpers.d.ts

@@ -0,0 +1,57 @@
+import type { InferType } from '@cleverbrush/schema';
+import { EXTRA_TYPE_BRAND, METHOD_LITERAL_BRAND, ObjectSchemaBuilder } from '@cleverbrush/schema';
+import type { Knex } from 'knex';
+import { POLYMORPHIC_TYPE_BRAND } from '../extension.js';
+import type { SchemaQueryBuilder } from '../SchemaQueryBuilder.js';
+import type { ResolvedVariantConfig, ValidatedSpec } from '../types.js';
+export type ScopesOf<S> = S extends {
+    readonly [METHOD_LITERAL_BRAND]?: infer N;
+} ? Extract<N, string> : never;
+export type ProjectionsOf<S> = S extends {
+    readonly [EXTRA_TYPE_BRAND]?: infer P;
+} ? P extends Record<string, readonly string[]> ? P : Record<never, never> : Record<never, never>;
+export type ProjectionKeysOf<S, K extends keyof ProjectionsOf<S> & string> = ProjectionsOf<S>[K] extends readonly (infer T extends string)[] ? T : string;
+export type QueryResultType<TLocalSchema> = TLocalSchema extends {
+    readonly [POLYMORPHIC_TYPE_BRAND]?: infer U;
+} ? NonNullable<U> : InferType<TLocalSchema>;
+export declare function resolveColumn(builder: SchemaQueryBuilder<any, any>, ref: any, label?: string): string | Knex.Raw;
+export declare function invalidateCache(builder: SchemaQueryBuilder<any, any>): void;
+export declare function getSoftDelete(builder: SchemaQueryBuilder<any, any>): {
+    column: string;
+} | null;
+export declare function getDefaultScope(builder: SchemaQueryBuilder<any, any>): Function | null;
+export declare function getTimestamps(builder: SchemaQueryBuilder<any, any>): {
+    createdAt: string;
+    updatedAt: string;
+} | null;
+declare const ALLOWED_OPS: Set<string>;
+export { ALLOWED_OPS };
+export declare function getVariantConfig(builder: SchemaQueryBuilder<any, any>): ResolvedVariantConfig | null;
+export declare function applyVariantJoins(builder: SchemaQueryBuilder<any, any>, base: Knex.QueryBuilder, variantConfig: ResolvedVariantConfig): Knex.QueryBuilder;
+export declare function registerSchemaQueryBuilder(ctor: new (...args: any[]) => any): void;
+export declare function getSchemaQueryBuilderCtor(): new (...args: any[]) => any;
+export declare function buildVariantRelationSelect(builder: SchemaQueryBuilder<any, any>, foreignSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any>, relAlias: string, foreignTableName: string, customize?: (q: SchemaQueryBuilder<any, any>) => void): Knex.Raw[];
+export declare function mapPolymorphicRow(builder: SchemaQueryBuilder<any, any>, row: Record<string, any>, variantConfig: ResolvedVariantConfig): Record<string, any>;
+export declare function resolveSchema(_builder: SchemaQueryBuilder<any, any>, schema: any): ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+export declare function findPrimaryKeyColumn(_builder: SchemaQueryBuilder<any, any>, schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>): string;
+export declare function resolvePkColumns(builder: SchemaQueryBuilder<any, any>): {
+    propertyKeys: readonly string[];
+    columnNames: readonly string[];
+};
+export declare function getEffectiveBaseQuery(builder: SchemaQueryBuilder<any, any>): Knex.QueryBuilder;
+export declare function buildJoinOne(builder: SchemaQueryBuilder<any, any>, resultQuery: Knex.QueryBuilder, spec: ValidatedSpec & {
+    type: 'one';
+}, relationAlias: string): void;
+export declare function buildJoinMany(builder: SchemaQueryBuilder<any, any>, resultQuery: Knex.QueryBuilder, spec: ValidatedSpec & {
+    type: 'many';
+}, relationAlias: string, i: number): void;
+export declare function buildQuery(builder: SchemaQueryBuilder<any, any>): Knex.QueryBuilder;
+export declare function getQuery(builder: SchemaQueryBuilder<any, any>): Knex.QueryBuilder;
+export declare function mapRow(builder: SchemaQueryBuilder<any, any>, row: Record<string, any>): Record<string, any>;
+export declare function cleanAndMapRow(builder: SchemaQueryBuilder<any, any>, row: Record<string, any>): Record<string, any>;
+export declare function mapObjectToColumns(builder: SchemaQueryBuilder<any, any>, obj: Record<string, any>): Record<string, any>;
+export declare function mapRecordToColumns(builder: SchemaQueryBuilder<any, any>, record: Record<string, any>): Record<string, any>;
+export declare function resolveColumnArg(builder: SchemaQueryBuilder<any, any>, col: any): string | Knex.Raw;
+export declare function isColumnAccessor(builder: SchemaQueryBuilder<any, any>, fn: Function): boolean;
+export declare function assertNotProjection(builder: SchemaQueryBuilder<any, any>, method: string): void;
+export declare function assertNotExplicitSelect(builder: SchemaQueryBuilder<any, any>, method: string): void;

package/dist/operations/insert.d.ts

@@ -0,0 +1,26 @@
+import type { InferType } 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> {
+    #private;
+    constructor(knex: Knex, localSchema: TLocalSchema, _parent: SchemaQueryBuilder<TLocalSchema, TResult>, conflictColumns: string[]);
+    merge(data: InsertType<TLocalSchema>, updateData?: Partial<InferType<TLocalSchema>>): Promise<TResult>;
+    ignore(data: InsertType<TLocalSchema>): Promise<TResult | undefined>;
+}
+export declare function insertImpl(builder: SchemaQueryBuilder<any, any>, data: InsertType<any>): Promise<any>;
+export declare function insertManyImpl(builder: SchemaQueryBuilder<any, any>, data: InsertType<any>[]): Promise<any[]>;
+export declare function onConflictImpl(builder: SchemaQueryBuilder<any, any>, ...conflictColumns: ColumnRef<any>[]): OnConflictBuilder<any, any>;
+export declare function upsertImpl(builder: SchemaQueryBuilder<any, any>, data: InsertType<any>, opts: {
+    conflictColumns: ColumnRef<any>[];
+    updateColumns?: ColumnRef<any>[];
+}): Promise<any>;
+export declare function bulkInsertImpl(builder: SchemaQueryBuilder<any, any>, rows: InsertType<any>[], opts?: {
+    chunkSize?: number;
+    onConflict?: 'ignore' | 'merge';
+    conflictColumns?: ColumnRef<any>[];
+}): Promise<any[]>;
+export declare function bulkUpsertImpl(builder: SchemaQueryBuilder<any, any>, rows: InsertType<any>[], opts: {
+    conflictColumns: ColumnRef<any>[];
+    chunkSize?: number;
+}): Promise<any[]>;

package/dist/operations/join.d.ts

@@ -0,0 +1,6 @@
+import type { SchemaQueryBuilder } from '../SchemaQueryBuilder.js';
+import type { JoinManySpec, JoinOneSpec } from '../types.js';
+export declare function joinOneImpl(builder: SchemaQueryBuilder<any, any>, spec: JoinOneSpec<any, any, any, any>): any;
+export declare function joinManyImpl(builder: SchemaQueryBuilder<any, any>, spec: JoinManySpec<any, any, any>): any;
+export declare function includeImpl(builder: SchemaQueryBuilder<any, any>, relationName: string, customize?: (q: SchemaQueryBuilder<any, any>) => void): any;
+export declare function includeVariantImpl(builder: SchemaQueryBuilder<any, any>, variantKey: string, relationName: string, customize?: (q: SchemaQueryBuilder<any, any>) => void): any;

package/dist/operations/pagination.d.ts

@@ -0,0 +1,15 @@
+import type { SchemaQueryBuilder } from '../SchemaQueryBuilder.js';
+import type { ColumnRef, CursorPaginationResult, PaginationResult } from '../types.js';
+export declare function limitImpl(builder: SchemaQueryBuilder<any, any>, n: number): any;
+export declare function offsetImpl(builder: SchemaQueryBuilder<any, any>, n: number): any;
+export declare function paginateImpl(builder: SchemaQueryBuilder<any, any>, opts: {
+    page: number;
+    pageSize: number;
+}): Promise<PaginationResult<any>>;
+export declare function paginateAfterImpl(builder: SchemaQueryBuilder<any, any>, opts: {
+    cursor?: any;
+    limit: number;
+    column?: ColumnRef<any>;
+    direction?: 'asc' | 'desc';
+}): Promise<CursorPaginationResult<any>>;
+export declare function executeImpl(builder: SchemaQueryBuilder<any, any>): Promise<any[]>;

package/dist/operations/select.d.ts

@@ -0,0 +1,15 @@
+import type { Knex } from 'knex';
+import type { SchemaQueryBuilder } from '../SchemaQueryBuilder.js';
+import type { ColumnRef } from '../types.js';
+export declare function selectImpl(builder: SchemaQueryBuilder<any, any>, ...args: unknown[]): any;
+export declare function distinctImpl(builder: SchemaQueryBuilder<any, any>, ...columns: (ColumnRef<any> | Knex.Raw)[]): any;
+export declare function countImpl(builder: SchemaQueryBuilder<any, any>, column?: ColumnRef<any> | Knex.Raw): any;
+export declare function countDistinctImpl(builder: SchemaQueryBuilder<any, any>, column?: ColumnRef<any> | Knex.Raw): any;
+export declare function minImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any> | Knex.Raw): any;
+export declare function maxImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any> | Knex.Raw): any;
+export declare function sumImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any> | Knex.Raw): any;
+export declare function avgImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any> | Knex.Raw): any;
+export declare function selectRawImpl(builder: SchemaQueryBuilder<any, any>, sql: string, bindings?: any[]): any;
+export declare function projectedImpl(builder: SchemaQueryBuilder<any, any>, name: string): any;
+export declare function scopedImpl(builder: SchemaQueryBuilder<any, any>, name: string): any;
+export declare function unscopedImpl(builder: SchemaQueryBuilder<any, any>): any;

package/dist/operations/state.d.ts

@@ -0,0 +1,39 @@
+import type { ObjectSchemaBuilder } from '@cleverbrush/schema';
+import type { Knex } from 'knex';
+import type { SchemaQueryBuilder } from '../SchemaQueryBuilder.js';
+import type { ResolvedVariantConfig, ValidatedSpec, VariantWhereFilter } from '../types.js';
+export interface QueryBuilderState {
+    knex: Knex;
+    baseQuery: Knex.QueryBuilder;
+    localSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    specs: ValidatedSpec[];
+    tableName: string;
+    /** SQL column names explicitly passed to `.select()`. null = SELECT *. */
+    explicitSelects: string[] | null;
+    /** Column-selection mode: null, 'select', 'aggregate', or 'projection'. */
+    selectionMode: 'select' | 'aggregate' | 'projection' | null;
+    /** Name of the projection currently applied, for error messages. */
+    appliedProjection: string | null;
+    /** When true, soft-delete filter is NOT applied. */
+    includeDeleted: boolean;
+    /** When true, only soft-deleted rows are returned. */
+    onlyDeleted: boolean;
+    /** When true, default scope is not applied. */
+    skipDefaultScope: boolean;
+    /** Resolved variant config, lazily populated. undefined = not yet read; null = not polymorphic. */
+    variantConfig: ResolvedVariantConfig | null | undefined;
+    /** When set, only these discriminator values are returned. null = all variants. */
+    enabledVariants: Set<string> | null;
+    /** Pending per-variant WHERE filters registered via .whereVariant(). */
+    variantWhereFilters: VariantWhereFilter[];
+    /** Variant-relation eager-load requests registered via .includeVariant(). */
+    variantRelationIncludes: Array<{
+        variantKey: string;
+        relationName: string;
+        customize?: (q: SchemaQueryBuilder<any, any>) => void;
+    }>;
+    /** Memoized result of buildQuery(). null = needs rebuild. */
+    cachedBuiltQuery: Knex.QueryBuilder | null;
+}
+export declare function getState(builder: SchemaQueryBuilder<any, any>): QueryBuilderState;
+export declare function setState(builder: SchemaQueryBuilder<any, any>, state: QueryBuilderState): void;

package/dist/operations/update.d.ts

@@ -0,0 +1,7 @@
+import type { InferType } from '@cleverbrush/schema';
+import type { SchemaQueryBuilder } from '../SchemaQueryBuilder.js';
+export declare function updateImpl(builder: SchemaQueryBuilder<any, any>, data: Partial<InferType<any>>): Promise<any[]>;
+export declare function bulkUpdateImpl(builder: SchemaQueryBuilder<any, any>, updates: ReadonlyArray<{
+    where: Partial<InferType<any>>;
+    set: Partial<InferType<any>>;
+}>): Promise<number>;

package/dist/operations/where.d.ts

@@ -0,0 +1,29 @@
+import type { Knex } from 'knex';
+import type { SchemaQueryBuilder } from '../SchemaQueryBuilder.js';
+import type { ColumnRef } from '../types.js';
+export declare function whereImpl(builder: SchemaQueryBuilder<any, any>, columnOrRaw: any, ...args: any[]): any;
+export declare function andWhereImpl(builder: SchemaQueryBuilder<any, any>, columnOrRaw: any, ...args: any[]): any;
+export declare function orWhereImpl(builder: SchemaQueryBuilder<any, any>, columnOrRaw: any, ...args: any[]): any;
+export declare function whereNotImpl(builder: SchemaQueryBuilder<any, any>, columnOrRaw: any, ...args: any[]): any;
+export declare function whereInImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>, values: readonly any[] | Knex.QueryBuilder): any;
+export declare function whereNotInImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>, values: readonly any[] | Knex.QueryBuilder): any;
+export declare function orWhereInImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>, values: readonly any[] | Knex.QueryBuilder): any;
+export declare function orWhereNotInImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>, values: readonly any[] | Knex.QueryBuilder): any;
+export declare function whereNullImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>): any;
+export declare function whereNotNullImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>): any;
+export declare function orWhereNullImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>): any;
+export declare function orWhereNotNullImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>): any;
+export declare function whereBetweenImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>, range: readonly [any, any]): any;
+export declare function whereNotBetweenImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>, range: readonly [any, any]): any;
+export declare function whereLikeImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>, value: string): any;
+export declare function whereILikeImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>, value: string): any;
+export declare function whereRawImpl(builder: SchemaQueryBuilder<any, any>, sql: string, ...bindings: any[]): any;
+export declare function whereExistsImpl(builder: SchemaQueryBuilder<any, any>, callback: Knex.QueryCallback | Knex.QueryBuilder): any;
+export declare function whereNotExistsImpl(builder: SchemaQueryBuilder<any, any>, callback: Knex.QueryCallback | Knex.QueryBuilder): any;
+export declare function whereJsonPathImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any>, path: string, operator?: string, value?: any): any;
+export declare function orderByImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any> | Knex.Raw, direction?: 'asc' | 'desc'): any;
+export declare function orderByRawImpl(builder: SchemaQueryBuilder<any, any>, sql: string, ...bindings: any[]): any;
+export declare function groupByImpl(builder: SchemaQueryBuilder<any, any>, ...columns: (ColumnRef<any> | Knex.Raw)[]): any;
+export declare function groupByRawImpl(builder: SchemaQueryBuilder<any, any>, sql: string, ...bindings: any[]): any;
+export declare function havingImpl(builder: SchemaQueryBuilder<any, any>, column: ColumnRef<any> | Knex.Raw, operator: string, value: any): any;
+export declare function havingRawImpl(builder: SchemaQueryBuilder<any, any>, sql: string, ...bindings: any[]): any;

package/dist/raw.d.ts

@@ -0,0 +1,35 @@
+import type { InferType, ObjectSchemaBuilder } from '@cleverbrush/schema';
+import type { Knex } from 'knex';
+/**
+ * Execute a raw SQL query or Knex query builder and map the result rows
+ * through the schema's column→property name mapping.
+ *
+ * This is the escape hatch for complex queries that can't be expressed with
+ * the typed `SchemaQueryBuilder` API. The schema is used only for result
+ * mapping — column names in the result are converted back to property names.
+ * Extra columns (not in the schema) are passed through unchanged.
+ *
+ * @param knex - A configured Knex instance.
+ * @param schema - The `ObjectSchemaBuilder` for result mapping.
+ * @param queryOrSql - A raw SQL string or a `Knex.QueryBuilder`.
+ * @param bindings - Optional bindings for parameterised SQL queries.
+ * @returns Mapped result rows.
+ *
+ * @example
+ * ```ts
+ * // Raw SQL with schema result mapping
+ * const results = await rawQuery(knex, PostSchema, `
+ *     SELECT p.*, COUNT(c.id) AS comment_count
+ *     FROM posts p
+ *     LEFT JOIN comments c ON c.post_id = p.id
+ *     GROUP BY p.id
+ *     ORDER BY comment_count DESC
+ *     LIMIT ?
+ * `, [10]);
+ *
+ * // Knex query builder as the source
+ * const subQuery = knex('posts').select('author_id', knex.raw('COUNT(*) as post_count')).groupBy('author_id');
+ * const results = await rawQuery(knex, UserSchema, subQuery);
+ * ```
+ */
+export declare function rawQuery<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(knex: Knex, schema: TSchema, queryOrSql: string | Knex.QueryBuilder, bindings?: any[]): Promise<(InferType<TSchema> & Record<string, any>)[]>;

package/dist/snapshot.d.ts

@@ -0,0 +1,39 @@
+import type { Entity } from './entity.js';
+import type { SchemaSnapshot } from './types.js';
+/**
+ * Build a {@link SchemaSnapshot} from a set of entities without a live DB.
+ *
+ * Handles polymorphic (CTI) entities by including each variant table.
+ * Deduplicates tables so STI variants sharing a base table are only included
+ * once.
+ *
+ * @param entities - The entities from your `EntityMap`.
+ * @returns A snapshot reflecting the current code-first schema state.
+ *
+ * @example
+ * ```ts
+ * const snapshot = entitiesToSnapshot(Object.values(entityMap));
+ * writeSnapshot('./migrations/snapshot.json', snapshot);
+ * ```
+ */
+export declare function entitiesToSnapshot(entities: Entity<any, any>[]): SchemaSnapshot;
+/**
+ * Load a {@link SchemaSnapshot} from disk.
+ *
+ * Returns an empty snapshot (no tables) when the file does not exist — this
+ * is the "first run" case, which causes `migrate generate` to emit a single
+ * migration containing `CREATE TABLE` for every entity.
+ *
+ * @param snapshotPath - Absolute or cwd-relative path to `snapshot.json`.
+ * @returns The parsed snapshot, or `{ version: 1, tables: {} }` if missing or
+ *   unreadable.
+ */
+export declare function loadSnapshot(snapshotPath: string): SchemaSnapshot;
+/**
+ * Write a {@link SchemaSnapshot} to disk atomically (temp-file + rename) with
+ * deterministic key ordering so diffs in version control are minimal.
+ *
+ * @param snapshotPath - Absolute or cwd-relative path to write `snapshot.json`.
+ * @param snapshot - The snapshot to serialize.
+ */
+export declare function writeSnapshot(snapshotPath: string, snapshot: SchemaSnapshot): void;