@cleverbrush/knex-schema 3.1.0 → 4.0.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/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;

package/dist/types.d.ts

@@ -89,4 +89,273 @@ export type ValidatedSpec = ({
     type: 'many';
 } & ValidatedJoinManySpec);
 export type InsertType<T extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = InferType<ReturnType<T['makeAllPropsOptional']>>;
+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
+ * schema was created with `.primaryKey()`).
+ *
+ * @internal
+ */
+type IsPkBranded<TPropSchema> = TPropSchema extends {
+    readonly [PRIMARY_KEY_BRAND]?: true;
+} ? true : false;
+/**
+ * Extract the primary-key column descriptor for a schema.
+ *
+ * Returns:
+ * - the literal property-key string for a single-column primary key
+ *   (e.g. `'id'`),
+ * - a tuple of property-key strings for a composite primary key
+ *   (e.g. `['userId', 'roleId']`),
+ * - or `never` if no primary key is declared.
+ *
+ * Composite primary keys are detected via the `COMPOSITE_PRIMARY_KEY_BRAND`
+ * placed on the object schema by `.hasPrimaryKey([...] as const)`. Use
+ * `as const` on the column tuple to preserve ordering at the type level.
+ *
+ * @public
+ */
+export type PrimaryKeyOf<S extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = S extends {
+    readonly [COMPOSITE_PRIMARY_KEY_BRAND]?: infer TCols;
+} ? TCols extends readonly string[] ? TCols : never : {
+    [K in keyof SchemaPropsForPk<S> & string]: IsPkBranded<SchemaPropsForPk<S>[K]> extends true ? K : never;
+}[keyof SchemaPropsForPk<S> & string];
+/**
+ * Extract the schema's property record for primary-key inference. Mirrors
+ * `SchemaProps` from `entity.ts` but lives here to avoid a circular import.
+ *
+ * @internal
+ */
+type SchemaPropsForPk<T> = T extends ObjectSchemaBuilder<infer P, any, any, any, any, any, any> ? P : never;
+/**
+ * The runtime value type of a schema's primary key.
+ *
+ * - For a single-column PK, the inferred type of that property
+ *   (e.g. `number`).
+ * - For a composite PK, a tuple of inferred property types in declared
+ *   order (e.g. `[number, number]`).
+ * - `never` if no primary key is declared.
+ *
+ * @public
+ */
+export type PrimaryKeyValueOf<S extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = PrimaryKeyOf<S> extends readonly (infer _Item extends string)[] ? PrimaryKeyOf<S> extends readonly string[] ? PkTupleValue<S, PrimaryKeyOf<S>> : never : PrimaryKeyOf<S> extends string ? InferType<S>[PrimaryKeyOf<S> & keyof InferType<S>] : never;
+/**
+ * Map a tuple of PK property-key names to their inferred value types.
+ *
+ * @internal
+ */
+type PkTupleValue<S extends ObjectSchemaBuilder<any, any, any, any, any, any, any>, TKeys extends readonly string[]> = {
+    [I in keyof TKeys]: TKeys[I] extends keyof InferType<S> ? InferType<S>[TKeys[I]] : unknown;
+};
+/**
+ * Extract the property schema captured inside a `PropertyDescriptor`.
+ *
+ * @internal
+ */
+type DescriptorPropertySchema<T> = T extends PropertyDescriptor<any, infer S, any, any> ? S : never;
+/**
+ * Result row type produced by a {@link SelectProjection} selector.
+ *
+ * Each entry's value is the {@link InferType} of the property schema the
+ * descriptor points at, so `.select(t => ({ id: t.id, n: t.title }))`
+ * yields `{ id: number; n: string }`.
+ *
+ * @public
+ */
+export type SelectProjection<R extends Record<string, unknown>> = {
+    [K in keyof R]: InferType<DescriptorPropertySchema<R[K]>>;
+};
+/**
+ * Callback shape accepted by the projection overload of `select`. The
+ * callback receives the schema's property-descriptor tree and returns an
+ * `{ alias: descriptor }` record.
+ *
+ * @public
+ */
+export type SelectSelector<T extends ObjectSchemaBuilder<any, any, any, any, any, any, any>> = (tree: PropertyDescriptorTree<SchemaBase<T>, SchemaBase<T>>) => Record<string, PropertyDescriptor<any, any, any>>;
+/** Result of offset-based pagination via {@link SchemaQueryBuilder.paginate}. */
+export interface PaginationResult<T> {
+    /** The rows for the current page. */
+    data: T[];
+    /** Total number of matching rows across all pages. */
+    total: number;
+    /** Current page number (1-based). */
+    page: number;
+    /** Number of rows per page. */
+    pageSize: number;
+    /** Total number of pages. */
+    totalPages: number;
+    /** Whether a next page exists. */
+    hasNextPage: boolean;
+    /** Whether a previous page exists. */
+    hasPreviousPage: boolean;
+}
+/** Result of cursor-based pagination via {@link SchemaQueryBuilder.paginateAfter}. */
+export interface CursorPaginationResult<T> {
+    /** The rows for the current page. */
+    data: T[];
+    /** Cursor value for the next page, or `null` if no more rows. */
+    nextCursor: string | null;
+    /** Whether more rows exist after this page. */
+    hasMore: boolean;
+}
+/** Storage strategy for a polymorphic variant. */
+export type VariantStorageType = 'cti' | 'sti';
+/** @internal Resolved form of a variant relation stored on {@link ResolvedVariantSpec}. */
+export interface ResolvedVariantRelationSpec {
+    name: string;
+    type: 'hasMany' | 'hasOne' | 'belongsTo' | 'belongsToMany';
+    schema: any;
+    /** Resolved FK *column* name on the variant or foreign table. */
+    foreignKey?: string;
+    through?: {
+        table: string;
+        localKey: string;
+        foreignKey: string;
+    };
+}
+/** @internal Resolved, normalised variant spec stored in schema extensions. */
+export interface ResolvedVariantSpec {
+    storage: VariantStorageType;
+    schema: ObjectSchemaBuilder<any, any, any, any, any, any, any>;
+    /** CTI: FK column name on the variant table. */
+    foreignKey?: string;
+    /** CTI: variant table name (from `schema.hasTableName()`). */
+    tableName?: string;
+    allowOrphan: boolean;
+    enforceCheck: boolean;
+    /** Variant-scoped relations (resolved), populated by `.withVariants()`. */
+    relations: ResolvedVariantRelationSpec[];
+}
+/** @internal Full variant config stored in the schema extension `'variants'`. */
+export interface ResolvedVariantConfig {
+    /** Property key on the base schema that is the discriminator. */
+    discriminatorKey: string;
+    /** SQL column name corresponding to `discriminatorKey`. Filled by query builder. */
+    discriminatorColumn: string;
+    /** Map from discriminator value → resolved variant spec. */
+    variants: Record<string, ResolvedVariantSpec>;
+}
+/** @internal Pending filter registered via `.whereVariant()`. */
+export interface VariantWhereFilter {
+    /** The discriminator value this filter applies to (e.g. `'image'`). */
+    key: string;
+    /** SQL column expression on the variant alias (e.g. `__v_image.width`). */
+    qualifiedColumn: string;
+    /** SQL comparison operator (validated). */
+    op: string;
+    value: any;
+}
+/** @internal Relation metadata stored via `.hasMany()`, `.belongsTo()`, etc. */
+export interface RelationSpec {
+    type: 'hasMany' | 'hasOne' | 'belongsTo' | 'belongsToMany';
+    name: string;
+    schema: any;
+    foreignKey?: any;
+    through?: {
+        table: string;
+        localKey: string;
+        foreignKey: string;
+    };
+}
+/** Column information read from the database. */
+export interface DatabaseColumnInfo {
+    name: string;
+    type: string;
+    nullable: boolean;
+    defaultValue: string | null;
+    maxLength: number | null;
+    numericPrecision: number | null;
+}
+/** Index information read from the database. */
+export interface DatabaseIndexInfo {
+    name: string;
+    columns: string[];
+    unique: boolean;
+    definition: string;
+}
+/** Foreign key information read from the database. */
+export interface DatabaseForeignKeyInfo {
+    constraintName: string;
+    columnName: string;
+    foreignTable: string;
+    foreignColumn: string;
+    deleteRule: string;
+    updateRule: string;
+}
+/** Check constraint information read from the database. */
+export interface DatabaseCheckInfo {
+    name: string;
+    definition: string;
+}
+/** Full database table state from introspection. */
+export interface DatabaseTableState {
+    columns: Record<string, DatabaseColumnInfo>;
+    indexes: DatabaseIndexInfo[];
+    foreignKeys: DatabaseForeignKeyInfo[];
+    checks: DatabaseCheckInfo[];
+}
+/**
+ * Serialized snapshot of all entity schemas at a given point in time.
+ *
+ * Stored in `<migrations.directory>/snapshot.json` and committed to version
+ * control. `migrate generate` diffs the current code against this snapshot
+ * (instead of a live database) to produce migration files, so no DB
+ * connection is required.
+ *
+ * Each entry in `tables` mirrors the shape that `introspectDatabase` would
+ * return — allowing `diffSchema` to be reused unchanged.
+ *
+ * @public
+ */
+export interface SchemaSnapshot {
+    version: 1;
+    /** Map of table name → database state derived from entity schemas. */
+    tables: Record<string, DatabaseTableState>;
+}
+/** A column to add in a migration. */
+export interface AddColumnDiff {
+    name: string;
+    type: string;
+    nullable: boolean;
+    defaultValue?: any;
+    references?: {
+        table: string;
+        column: string;
+    };
+    onDelete?: string;
+    onUpdate?: string;
+}
+/** Changes to apply to an existing column. */
+export interface AlterColumnDiff {
+    name: string;
+    changes: Record<string, {
+        from: any;
+        to: any;
+    }>;
+}
+/** An index to add in a migration. */
+export interface AddIndexDiff {
+    columns: string[];
+    name?: string;
+    unique?: boolean;
+}
+/** A foreign key to add in a migration. */
+export interface AddForeignKeyDiff {
+    column: string;
+    foreignTable: string;
+    foreignColumn: string;
+    onDelete?: string;
+    onUpdate?: string;
+}
+/** Schema diff result between the code-first model and the live database. */
+export interface MigrationDiff {
+    addColumns: AddColumnDiff[];
+    dropColumns: string[];
+    alterColumns: AlterColumnDiff[];
+    addIndexes: AddIndexDiff[];
+    dropIndexes: string[];
+    addForeignKeys: AddForeignKeyDiff[];
+    dropForeignKeys: string[];
+}
 export {};

package/package.json

@@ -5,7 +5,7 @@
         "email": "andrew_zol@cleverbrush.com"
     },
     "dependencies": {
-        "@cleverbrush/schema": "^3.1.0"
+        "@cleverbrush/schema": "^4.0.0"
     },
     "peerDependencies": {
         "knex": ">=3.1.0"
@@ -32,6 +32,10 @@
         ".": {
             "types": "./dist/index.d.ts",
             "import": "./dist/index.js"
+        },
+        "./extension": {
+            "types": "./dist/extension.d.ts",
+            "import": "./dist/extension.js"
         }
     },
     "sideEffects": false,
@@ -48,5 +52,5 @@
     },
     "type": "module",
     "types": "./dist/index.d.ts",
-    "version": "3.1.0"
+    "version": "4.0.0"
 }