noormme 1.0.0

package/dist/cjs/util/type-utils.d.ts

@@ -0,0 +1,189 @@
+import { InsertResult } from '../query-builder/insert-result.js';
+import { DeleteResult } from '../query-builder/delete-result.js';
+import { UpdateResult } from '../query-builder/update-result.js';
+import { KyselyTypeError } from './type-error.js';
+import { MergeResult } from '../query-builder/merge-result.js';
+/**
+ * Given a database type and a union of table names in that db, returns
+ * a union type with all possible column names.
+ *
+ * Example:
+ *
+ * ```ts
+ * interface Person {
+ *   id: number
+ * }
+ *
+ * interface Pet {
+ *   name: string
+ *   species: 'cat' | 'dog'
+ * }
+ *
+ * interface Movie {
+ *   stars: number
+ * }
+ *
+ * interface Database {
+ *   person: Person
+ *   pet: Pet
+ *   movie: Movie
+ * }
+ *
+ * type Columns = AnyColumn<Database, 'person' | 'pet'>
+ *
+ * // Columns == 'id' | 'name' | 'species'
+ * ```
+ */
+export type AnyColumn<DB, TB extends keyof DB> = {
+    [T in TB]: keyof DB[T];
+}[TB] & string;
+/**
+ * Extracts a column type.
+ */
+export type ExtractColumnType<DB, TB extends keyof DB, C> = {
+    [T in TB]: C extends keyof DB[T] ? DB[T][C] : never;
+}[TB];
+/**
+ * Given a database type and a union of table names in that db, returns
+ * a union type with all possible `table`.`column` combinations.
+ *
+ * Example:
+ *
+ * ```ts
+ * interface Person {
+ *   id: number
+ * }
+ *
+ * interface Pet {
+ *   name: string
+ *   species: 'cat' | 'dog'
+ * }
+ *
+ * interface Movie {
+ *   stars: number
+ * }
+ *
+ * interface Database {
+ *   person: Person
+ *   pet: Pet
+ *   movie: Movie
+ * }
+ *
+ * type Columns = AnyColumnWithTable<Database, 'person' | 'pet'>
+ *
+ * // Columns == 'person.id' | 'pet.name' | 'pet.species'
+ * ```
+ */
+export type AnyColumnWithTable<DB, TB extends keyof DB> = {
+    [T in TB]: `${T & string}.${keyof DB[T] & string}`;
+}[TB];
+/**
+ * Just like {@link AnyColumn} but with a ` as <string>` suffix.
+ */
+export type AnyAliasedColumn<DB, TB extends keyof DB> = `${AnyColumn<DB, TB>} as ${string}`;
+/**
+ * Just like {@link AnyColumnWithTable} but with a ` as <string>` suffix.
+ */
+export type AnyAliasedColumnWithTable<DB, TB extends keyof DB> = `${AnyColumnWithTable<DB, TB>} as ${string}`;
+/**
+ * Extracts the item type of an array.
+ */
+export type ArrayItemType<T> = T extends ReadonlyArray<infer I> ? I : never;
+export type SimplifySingleResult<O> = O extends InsertResult ? O : O extends DeleteResult ? O : O extends UpdateResult ? O : O extends MergeResult ? O : Simplify<O> | undefined;
+export type SimplifyResult<O> = O extends InsertResult ? O : O extends DeleteResult ? O : O extends UpdateResult ? O : O extends MergeResult ? O : Simplify<O>;
+export type Simplify<T> = DrainOuterGeneric<{
+    [K in keyof T]: T[K];
+} & {}>;
+/**
+ * Represents a database row whose column names and their types are unknown.
+ */
+export type UnknownRow = Record<string, unknown>;
+/**
+ * Makes all properties of object type `T` nullable.
+ */
+export type Nullable<T> = {
+    [P in keyof T]: T[P] | null;
+};
+/**
+ * Evaluates to `true` if `T` is `never`.
+ */
+export type IsNever<T> = [T] extends [never] ? true : false;
+/**
+ * Evaluates to `true` if `T` is `any`.
+ */
+export type IsAny<T> = 0 extends T & 1 ? true : false;
+/**
+ * Evaluates to `true` if the types `T` and `U` are equal.
+ */
+export type Equals<T, U> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? true : false;
+export type NarrowPartial<O, T> = DrainOuterGeneric<T extends object ? {
+    [K in keyof O & string]: K extends keyof T ? T[K] extends NotNull ? Exclude<O[K], null> : T[K] extends O[K] ? T[K] : KyselyTypeError<`$narrowType() call failed: passed type does not exist in '${K}'s type union`> : O[K];
+} : never>;
+/**
+ * A type constant for marking a column as not null. Can be used with `$narrowPartial`.
+ *
+ * Example:
+ *
+ * ```ts
+ * import type { NotNull } from 'kysely'
+ *
+ * await db.selectFrom('person')
+ *   .where('nullable_column', 'is not', null)
+ *   .selectAll()
+ *   .$narrowType<{ nullable_column: NotNull }>()
+ *   .executeTakeFirstOrThrow()
+ * ```
+ */
+export type NotNull = {
+    readonly __notNull__: unique symbol;
+};
+export type SqlBool = boolean | 0 | 1;
+/**
+ * Utility to reduce depth of TypeScript's internal type instantiation stack.
+ *
+ * Example:
+ *
+ * ```ts
+ * type A<T> = { item: T }
+ *
+ * type Test<T> = A<
+ *   A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<T>>>>>>>>>>>>>>>>>>>>>>>>
+ * >
+ *
+ * // type Error = Test<number> // Type instantiation is excessively deep and possibly infinite.ts (2589)
+ * ```
+ *
+ * To fix this, we can use `DrainOuterGeneric`:
+ *
+ * ```ts
+ * type A<T> = DrainOuterGeneric<{ item: T }>
+ *
+ * type Test<T> = A<
+ *  A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<A<T>>>>>>>>>>>>>>>>>>>>>>>>
+ * >
+ *
+ * type Ok = Test<number> // Ok
+ * ```
+ */
+export type DrainOuterGeneric<T> = [T] extends [unknown] ? T : never;
+export type ShallowRecord<K extends keyof any, T> = DrainOuterGeneric<{
+    [P in K]: T;
+}>;
+/**
+ * Dehydrates any root properties of an object that are not valid JSON types.
+ *
+ * For now, we catch anything in {@link StringsWhenDataTypeNotAvailable} and convert it to `string`.
+ */
+export type ShallowDehydrateObject<O> = {
+    [K in keyof O]: ShallowDehydrateValue<O[K]>;
+};
+/**
+ * Dehydrates a value when it is not a valid JSON type.
+ *
+ * For now, we catch anything in {@link StringsWhenDataTypeNotAvailable} and convert it to `string`,
+ * and anything in {@link NumbersWhenDataTypeNotAvailable} and convert it to `number`.
+ */
+export type ShallowDehydrateValue<T> = T extends null | undefined ? T : T extends (infer U)[] | null | undefined ? Array<ShallowDehydrateValue<U>> | Extract<T, null | undefined> : Exclude<T, StringsWhenDataTypeNotAvailable | NumbersWhenDataTypeNotAvailable> | ([Extract<T, NumbersWhenDataTypeNotAvailable>] extends [never] ? never : number) | ([Extract<T, StringsWhenDataTypeNotAvailable>] extends [never] ? never : string);
+export type StringsWhenDataTypeNotAvailable = Date | Uint8Array;
+export type NumbersWhenDataTypeNotAvailable = bigint | NumericString;
+export type NumericString = `${number}`;

package/dist/cjs/util/type-utils.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/utils/errorHelpers.d.ts

@@ -0,0 +1,26 @@
+import { NoormError } from '../errors/NoormError.js';
+/**
+ * Wraps Kysely errors with more context-aware NoormError instances
+ */
+export declare function wrapKyselyError(error: any, context: {
+    table?: string;
+    operation?: string;
+    availableColumns?: string[];
+    availableTables?: string[];
+}): NoormError;
+/**
+ * Extract column name from PostgreSQL/MySQL error messages
+ */
+export declare function extractColumnName(errorMessage: string): string | null;
+/**
+ * Extract table name from database error messages
+ */
+export declare function extractTableName(errorMessage: string): string | null;
+/**
+ * Extract constraint information from error messages
+ */
+export declare function extractConstraintMessage(errorMessage: string): string;
+/**
+ * Suggests corrections for typos in table/column names
+ */
+export declare function suggestCorrections(input: string, available: string[], maxSuggestions?: number): string[];

package/dist/cjs/utils/errorHelpers.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapKyselyError = wrapKyselyError;
+exports.extractColumnName = extractColumnName;
+exports.extractTableName = extractTableName;
+exports.extractConstraintMessage = extractConstraintMessage;
+exports.suggestCorrections = suggestCorrections;
+const NoormError_js_1 = require("../errors/NoormError.js");
+/**
+ * Wraps Kysely errors with more context-aware NoormError instances
+ */
+function wrapKyselyError(error, context) {
+    const message = error.message || String(error);
+    // Handle column not found errors
+    if (message.includes('column') && message.includes('does not exist')) {
+        const columnName = extractColumnName(message);
+        if (columnName && context.table && context.availableColumns) {
+            return new NoormError_js_1.ColumnNotFoundError(columnName, context.table, context.availableColumns);
+        }
+    }
+    // Handle table not found errors
+    if (message.includes('relation') && message.includes('does not exist')) {
+        const tableName = extractTableName(message);
+        if (tableName && context.availableTables) {
+            return new NoormError_js_1.TableNotFoundError(tableName, context.availableTables);
+        }
+    }
+    // Handle connection errors
+    if (message.includes('connect') || message.includes('ECONNREFUSED') || message.includes('ENOTFOUND')) {
+        return new NoormError_js_1.ConnectionError(message, error);
+    }
+    // Handle authentication errors
+    if (message.includes('authentication') || message.includes('password') || message.includes('SASL')) {
+        return new NoormError_js_1.ConnectionError('Authentication failed. Check your username and password.', error);
+    }
+    // Handle syntax errors
+    if (message.includes('syntax error') || message.includes('near')) {
+        return new NoormError_js_1.NoormError(`SQL syntax error: ${message}`, {
+            table: context.table,
+            operation: context.operation,
+            suggestion: 'Check your query syntax or report this as a bug if you\'re using NOORMME methods',
+            originalError: error
+        });
+    }
+    // Handle constraint violations
+    if (message.includes('constraint') || message.includes('duplicate') || message.includes('unique')) {
+        return new NoormError_js_1.NoormError(`Database constraint violation: ${extractConstraintMessage(message)}`, {
+            table: context.table,
+            operation: context.operation,
+            suggestion: 'Check for duplicate values or foreign key violations',
+            originalError: error
+        });
+    }
+    // Generic wrapper for other errors
+    return new NoormError_js_1.NoormError(message, {
+        table: context.table,
+        operation: context.operation,
+        suggestion: 'Check the database connection and query parameters',
+        originalError: error
+    });
+}
+/**
+ * Extract column name from PostgreSQL/MySQL error messages
+ */
+function extractColumnName(errorMessage) {
+    // PostgreSQL: column "column_name" does not exist
+    let match = errorMessage.match(/column "([^"]+)" does not exist/i);
+    if (match)
+        return match[1];
+    // MySQL: Unknown column 'column_name' in 'field list'
+    match = errorMessage.match(/Unknown column '([^']+)'/i);
+    if (match)
+        return match[1];
+    // SQLite: no such column: column_name
+    match = errorMessage.match(/no such column: (\w+)/i);
+    if (match)
+        return match[1];
+    return null;
+}
+/**
+ * Extract table name from database error messages
+ */
+function extractTableName(errorMessage) {
+    // PostgreSQL: relation "table_name" does not exist
+    let match = errorMessage.match(/relation "([^"]+)" does not exist/i);
+    if (match)
+        return match[1];
+    // MySQL: Table 'database.table_name' doesn't exist
+    match = errorMessage.match(/Table '[^.]+\.([^']+)' doesn't exist/i);
+    if (match)
+        return match[1];
+    // SQLite: no such table: table_name
+    match = errorMessage.match(/no such table: (\w+)/i);
+    if (match)
+        return match[1];
+    return null;
+}
+/**
+ * Extract constraint information from error messages
+ */
+function extractConstraintMessage(errorMessage) {
+    // Try to extract a more user-friendly constraint message
+    if (errorMessage.includes('duplicate key')) {
+        return 'Duplicate value violates unique constraint';
+    }
+    if (errorMessage.includes('foreign key')) {
+        return 'Foreign key constraint violation';
+    }
+    if (errorMessage.includes('check constraint')) {
+        return 'Check constraint violation';
+    }
+    if (errorMessage.includes('not null')) {
+        return 'Required field cannot be null';
+    }
+    return errorMessage;
+}
+/**
+ * Suggests corrections for typos in table/column names
+ */
+function suggestCorrections(input, available, maxSuggestions = 3) {
+    const suggestions = [];
+    for (const option of available) {
+        const score = calculateSimilarity(input.toLowerCase(), option.toLowerCase());
+        if (score > 0.3) { // Only suggest if similarity > 30%
+            suggestions.push({ name: option, score });
+        }
+    }
+    return suggestions
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxSuggestions)
+        .map(s => s.name);
+}
+/**
+ * Calculate string similarity using Jaro-Winkler algorithm (simplified)
+ */
+function calculateSimilarity(str1, str2) {
+    if (str1 === str2)
+        return 1;
+    const len1 = str1.length;
+    const len2 = str2.length;
+    if (len1 === 0 || len2 === 0)
+        return 0;
+    const matchWindow = Math.floor(Math.max(len1, len2) / 2) - 1;
+    if (matchWindow < 0)
+        return 0;
+    const str1Matches = new Array(len1).fill(false);
+    const str2Matches = new Array(len2).fill(false);
+    let matches = 0;
+    let transpositions = 0;
+    // Find matches
+    for (let i = 0; i < len1; i++) {
+        const start = Math.max(0, i - matchWindow);
+        const end = Math.min(i + matchWindow + 1, len2);
+        for (let j = start; j < end; j++) {
+            if (str2Matches[j] || str1[i] !== str2[j])
+                continue;
+            str1Matches[i] = true;
+            str2Matches[j] = true;
+            matches++;
+            break;
+        }
+    }
+    if (matches === 0)
+        return 0;
+    // Find transpositions
+    let k = 0;
+    for (let i = 0; i < len1; i++) {
+        if (!str1Matches[i])
+            continue;
+        while (!str2Matches[k])
+            k++;
+        if (str1[i] !== str2[k])
+            transpositions++;
+        k++;
+    }
+    const jaro = (matches / len1 + matches / len2 + (matches - transpositions / 2) / matches) / 3;
+    // Jaro-Winkler bonus for common prefix
+    let prefix = 0;
+    for (let i = 0; i < Math.min(len1, len2, 4); i++) {
+        if (str1[i] === str2[i])
+            prefix++;
+        else
+            break;
+    }
+    return jaro + 0.1 * prefix * (1 - jaro);
+}

package/dist/cjs/watch/schema-watcher.d.ts

@@ -0,0 +1,68 @@
+import type { Kysely } from '../kysely.js';
+import { SchemaChange } from '../types/index.js';
+import { Logger } from '../logging/logger.js';
+import { SchemaDiscovery } from '../schema/schema-discovery.js';
+export interface WatchOptions {
+    pollInterval?: number;
+    ignoreViews?: boolean;
+    ignoredTables?: string[];
+    enabled?: boolean;
+}
+/**
+ * Monitors database schema changes in development mode
+ */
+export declare class SchemaWatcher {
+    private db;
+    private schemaDiscovery;
+    private logger;
+    private options;
+    private isWatching;
+    private intervalId;
+    private lastSchemaHash;
+    private callbacks;
+    constructor(db: Kysely<any>, schemaDiscovery: SchemaDiscovery, logger: Logger, options?: WatchOptions);
+    /**
+     * Start watching for schema changes
+     */
+    startWatching(): Promise<void>;
+    /**
+     * Stop watching for schema changes
+     */
+    stopWatching(): void;
+    /**
+     * Register callback for schema changes
+     */
+    onSchemaChange(callback: (changes: SchemaChange[]) => void): void;
+    /**
+     * Remove callback for schema changes
+     */
+    removeSchemaChangeCallback(callback: (changes: SchemaChange[]) => void): void;
+    /**
+     * Manually trigger schema check
+     */
+    checkForChanges(): Promise<SchemaChange[]>;
+    /**
+     * Get current database schema
+     */
+    private getCurrentSchema;
+    /**
+     * Create a hash of the schema for change detection
+     */
+    private hashSchema;
+    /**
+     * Detect specific changes between schemas
+     */
+    private detectChanges;
+    /**
+     * Notify all registered callbacks about schema changes
+     */
+    private notifyCallbacks;
+    /**
+     * Get current watching status
+     */
+    isCurrentlyWatching(): boolean;
+    /**
+     * Get watch configuration
+     */
+    getWatchOptions(): WatchOptions;
+}

package/dist/cjs/watch/schema-watcher.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaWatcher = void 0;
+/**
+ * Monitors database schema changes in development mode
+ */
+class SchemaWatcher {
+    db;
+    schemaDiscovery;
+    logger;
+    options;
+    isWatching = false;
+    intervalId = null;
+    lastSchemaHash = null;
+    callbacks = [];
+    constructor(db, schemaDiscovery, logger, options = {}) {
+        this.db = db;
+        this.schemaDiscovery = schemaDiscovery;
+        this.logger = logger;
+        this.options = options;
+        this.options = {
+            pollInterval: 5000,
+            ignoreViews: true,
+            ignoredTables: [],
+            enabled: process.env.NODE_ENV === 'development',
+            ...options
+        };
+    }
+    /**
+     * Start watching for schema changes
+     */
+    async startWatching() {
+        if (!this.options.enabled) {
+            this.logger.debug('Schema watching disabled (not in development mode)');
+            return;
+        }
+        if (this.isWatching) {
+            this.logger.warn('Schema watcher already running');
+            return;
+        }
+        this.logger.info('Starting schema change monitoring...');
+        // Get initial schema snapshot
+        const initialSchema = await this.getCurrentSchema();
+        this.lastSchemaHash = this.hashSchema(initialSchema);
+        this.isWatching = true;
+        this.intervalId = setInterval(() => {
+            this.checkForChanges().catch(error => {
+                this.logger.error('Error checking for schema changes:', error);
+            });
+        }, this.options.pollInterval);
+        this.logger.info(`Schema watcher started (polling every ${this.options.pollInterval}ms)`);
+    }
+    /**
+     * Stop watching for schema changes
+     */
+    stopWatching() {
+        if (!this.isWatching) {
+            return;
+        }
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+        this.isWatching = false;
+        this.logger.info('Schema watcher stopped');
+    }
+    /**
+     * Register callback for schema changes
+     */
+    onSchemaChange(callback) {
+        this.callbacks.push(callback);
+    }
+    /**
+     * Remove callback for schema changes
+     */
+    removeSchemaChangeCallback(callback) {
+        const index = this.callbacks.indexOf(callback);
+        if (index > -1) {
+            this.callbacks.splice(index, 1);
+        }
+    }
+    /**
+     * Manually trigger schema check
+     */
+    async checkForChanges() {
+        try {
+            const currentSchema = await this.getCurrentSchema();
+            const currentHash = this.hashSchema(currentSchema);
+            if (this.lastSchemaHash && currentHash !== this.lastSchemaHash) {
+                this.logger.info('Schema changes detected, analyzing...');
+                // Since we only have the hash, we'll need to do a full schema comparison
+                // In a production implementation, you'd store the full previous schema
+                const changes = await this.detectChanges();
+                this.lastSchemaHash = currentHash;
+                if (changes.length > 0) {
+                    this.logger.info(`Found ${changes.length} schema changes`);
+                    this.notifyCallbacks(changes);
+                }
+                return changes;
+            }
+            return [];
+        }
+        catch (error) {
+            this.logger.error('Failed to check for schema changes:', error);
+            return [];
+        }
+    }
+    /**
+     * Get current database schema
+     */
+    async getCurrentSchema() {
+        return await this.schemaDiscovery.discoverSchema();
+    }
+    /**
+     * Create a hash of the schema for change detection
+     */
+    hashSchema(schema) {
+        // Create a deterministic string representation of the schema
+        const schemaString = JSON.stringify({
+            tables: schema.tables
+                .filter(table => !this.options.ignoredTables?.includes(table.name))
+                .map(table => ({
+                name: table.name,
+                columns: table.columns.map(col => ({
+                    name: col.name,
+                    type: col.type,
+                    nullable: col.nullable,
+                    isPrimaryKey: col.isPrimaryKey,
+                    defaultValue: col.defaultValue
+                })),
+                primaryKey: table.primaryKey,
+                foreignKeys: table.foreignKeys,
+                indexes: table.indexes
+            }))
+                .sort((a, b) => a.name.localeCompare(b.name)),
+            relationships: schema.relationships
+                .sort((a, b) => `${a.fromTable}.${a.name}`.localeCompare(`${b.fromTable}.${b.name}`))
+        });
+        // Simple hash function
+        let hash = 0;
+        for (let i = 0; i < schemaString.length; i++) {
+            const char = schemaString.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        return hash.toString();
+    }
+    /**
+     * Detect specific changes between schemas
+     */
+    async detectChanges() {
+        // In a real implementation, you'd compare the old and new schemas
+        // For now, return a generic change notification
+        return [{
+                type: 'table_added', // This would be determined by actual comparison
+                table: 'unknown',
+                details: 'Schema change detected - full refresh recommended'
+            }];
+    }
+    /**
+     * Notify all registered callbacks about schema changes
+     */
+    notifyCallbacks(changes) {
+        this.callbacks.forEach(callback => {
+            try {
+                callback(changes);
+            }
+            catch (error) {
+                this.logger.error('Error in schema change callback:', error);
+            }
+        });
+    }
+    /**
+     * Get current watching status
+     */
+    isCurrentlyWatching() {
+        return this.isWatching;
+    }
+    /**
+     * Get watch configuration
+     */
+    getWatchOptions() {
+        return { ...this.options };
+    }
+}
+exports.SchemaWatcher = SchemaWatcher;