noormme 1.0.0

package/dist/esm/dynamic/dynamic.js

@@ -0,0 +1,129 @@
+/// <reference types="./dynamic.d.ts" />
+import { DynamicReferenceBuilder } from './dynamic-reference-builder.js';
+import { DynamicTableBuilder } from './dynamic-table-builder.js';
+export class DynamicModule {
+    /**
+     * Creates a dynamic reference to a column that is not know at compile time.
+     *
+     * Kysely is built in a way that by default you can't refer to tables or columns
+     * that are not actually visible in the current query and context. This is all
+     * done by TypeScript at compile time, which means that you need to know the
+     * columns and tables at compile time. This is not always the case of course.
+     *
+     * This method is meant to be used in those cases where the column names
+     * come from the user input or are not otherwise known at compile time.
+     *
+     * WARNING! Unlike values, column names are not escaped by the database engine
+     * or Kysely and if you pass in unchecked column names using this method, you
+     * create an SQL injection vulnerability. Always __always__ validate the user
+     * input before passing it to this method.
+     *
+     * There are couple of examples below for some use cases, but you can pass
+     * `ref` to other methods as well. If the types allow you to pass a `ref`
+     * value to some place, it should work.
+     *
+     * ### Examples
+     *
+     * Filter by a column not know at compile time:
+     *
+     * ```ts
+     * async function someQuery(filterColumn: string, filterValue: string) {
+     *   const { ref } = db.dynamic
+     *
+     *   return await db
+     *     .selectFrom('person')
+     *     .selectAll()
+     *     .where(ref(filterColumn), '=', filterValue)
+     *     .execute()
+     * }
+     *
+     * someQuery('first_name', 'Arnold')
+     * someQuery('person.last_name', 'Aniston')
+     * ```
+     *
+     * Order by a column not know at compile time:
+     *
+     * ```ts
+     * async function someQuery(orderBy: string) {
+     *   const { ref } = db.dynamic
+     *
+     *   return await db
+     *     .selectFrom('person')
+     *     .select('person.first_name as fn')
+     *     .orderBy(ref(orderBy))
+     *     .execute()
+     * }
+     *
+     * someQuery('fn')
+     * ```
+     *
+     * In this example we add selections dynamically:
+     *
+     * ```ts
+     * const { ref } = db.dynamic
+     *
+     * // Some column name provided by the user. Value not known at compile time.
+     * const columnFromUserInput: PossibleColumns = 'birthdate';
+     *
+     * // A type that lists all possible values `columnFromUserInput` can have.
+     * // You can use `keyof Person` if any column of an interface is allowed.
+     * type PossibleColumns = 'last_name' | 'first_name' | 'birthdate'
+     *
+     * const [person] = await db.selectFrom('person')
+     *   .select([
+     *     ref<PossibleColumns>(columnFromUserInput),
+     *     'id'
+     *   ])
+     *   .execute()
+     *
+     * // The resulting type contains all `PossibleColumns` as optional fields
+     * // because we cannot know which field was actually selected before
+     * // running the code.
+     * const lastName: string | null | undefined = person?.last_name
+     * const firstName: string | undefined = person?.first_name
+     * const birthDate: Date | null | undefined = person?.birthdate
+     *
+     * // The result type also contains the compile time selection `id`.
+     * person?.id
+     * ```
+     */
+    ref(reference) {
+        return new DynamicReferenceBuilder(reference);
+    }
+    /**
+     * Creates a table reference to a table that's not fully known at compile time.
+     *
+     * The type `T` is allowed to be a union of multiple tables.
+     *
+     * <!-- siteExample("select", "Generic find query", 130) -->
+     *
+     * A generic type-safe helper function for finding a row by a column value:
+     *
+     * ```ts
+     * import { SelectType } from 'kysely'
+     * import { Database } from 'type-editor'
+     *
+     * async function getRowByColumn<
+     *   T extends keyof Database,
+     *   C extends keyof Database[T] & string,
+     *   V extends SelectType<Database[T][C]>,
+     * >(t: T, c: C, v: V) {
+     *   // We need to use the dynamic module since the table name
+     *   // is not known at compile time.
+     *   const { table, ref } = db.dynamic
+     *
+     *   return await db
+     *     .selectFrom(table(t).as('t'))
+     *     .selectAll()
+     *     .where(ref(c), '=', v)
+     *     .orderBy('t.id')
+     *     .executeTakeFirstOrThrow()
+     * }
+     *
+     * const person = await getRowByColumn('person', 'first_name', 'Arnold')
+     * ```
+     */
+    table(table) {
+        return new DynamicTableBuilder(table);
+    }
+}

package/dist/esm/errors/NoormError.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Enhanced error class with context-aware information
+ */
+export declare class NoormError extends Error {
+    context: {
+        table?: string;
+        operation?: string;
+        suggestion?: string;
+        availableOptions?: string[];
+        originalError?: Error;
+    };
+    constructor(message: string, context?: {
+        table?: string;
+        operation?: string;
+        suggestion?: string;
+        availableOptions?: string[];
+        originalError?: Error;
+    });
+    /**
+     * Get a formatted error message with context
+     */
+    getFormattedMessage(): string;
+    /**
+     * Convert to JSON for logging/debugging
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        context: {
+            table?: string;
+            operation?: string;
+            suggestion?: string;
+            availableOptions?: string[];
+            originalError?: Error;
+        };
+        stack: string | undefined;
+    };
+}
+/**
+ * Specific error types for common scenarios
+ */
+export declare class TableNotFoundError extends NoormError {
+    constructor(tableName: string, availableTables?: string[]);
+}
+export declare class ColumnNotFoundError extends NoormError {
+    constructor(columnName: string, tableName: string, availableColumns?: string[]);
+}
+export declare class RelationshipNotFoundError extends NoormError {
+    constructor(relationshipName: string, tableName: string, availableRelationships?: string[]);
+}
+export declare class ValidationError extends NoormError {
+    constructor(message: string, field?: string, tableName?: string);
+}
+export declare class ConnectionError extends NoormError {
+    constructor(message: string, originalError?: Error);
+}

package/dist/esm/errors/NoormError.js

@@ -0,0 +1,150 @@
+/// <reference types="./NoormError.d.ts" />
+/**
+ * Enhanced error class with context-aware information
+ */
+export class NoormError extends Error {
+    context;
+    constructor(message, context = {}) {
+        super(message);
+        this.context = context;
+        this.name = 'NoormError';
+        // Maintain stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, NoormError);
+        }
+    }
+    /**
+     * Get a formatted error message with context
+     */
+    getFormattedMessage() {
+        let formatted = this.message;
+        if (this.context.table) {
+            formatted += `\n  Table: ${this.context.table}`;
+        }
+        if (this.context.operation) {
+            formatted += `\n  Operation: ${this.context.operation}`;
+        }
+        if (this.context.suggestion) {
+            formatted += `\n  Suggestion: ${this.context.suggestion}`;
+        }
+        if (this.context.availableOptions && this.context.availableOptions.length > 0) {
+            formatted += `\n  Available options: ${this.context.availableOptions.join(', ')}`;
+        }
+        if (this.context.originalError) {
+            formatted += `\n  Original error: ${this.context.originalError.message}`;
+        }
+        return formatted;
+    }
+    /**
+     * Convert to JSON for logging/debugging
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            context: this.context,
+            stack: this.stack
+        };
+    }
+}
+/**
+ * Specific error types for common scenarios
+ */
+export class TableNotFoundError extends NoormError {
+    constructor(tableName, availableTables = []) {
+        super(`Table '${tableName}' not found in schema`, {
+            table: tableName,
+            operation: 'schema_lookup',
+            suggestion: availableTables.length > 0
+                ? `Available tables: ${availableTables.join(', ')}`
+                : 'Check your database connection and schema',
+            availableOptions: availableTables
+        });
+    }
+}
+export class ColumnNotFoundError extends NoormError {
+    constructor(columnName, tableName, availableColumns = []) {
+        const similar = findSimilarColumns(availableColumns, columnName);
+        super(`Column '${columnName}' not found on table '${tableName}'`, {
+            table: tableName,
+            operation: 'column_lookup',
+            suggestion: similar.length > 0
+                ? `Did you mean '${similar[0]}'?`
+                : `Available columns: ${availableColumns.join(', ')}`,
+            availableOptions: availableColumns
+        });
+    }
+}
+export class RelationshipNotFoundError extends NoormError {
+    constructor(relationshipName, tableName, availableRelationships = []) {
+        super(`Relationship '${relationshipName}' not found on table '${tableName}'`, {
+            table: tableName,
+            operation: 'relationship_lookup',
+            suggestion: availableRelationships.length > 0
+                ? `Available relationships: ${availableRelationships.join(', ')}`
+                : 'No relationships defined for this table',
+            availableOptions: availableRelationships
+        });
+    }
+}
+export class ValidationError extends NoormError {
+    constructor(message, field, tableName) {
+        super(message, {
+            table: tableName,
+            operation: 'validation',
+            suggestion: field ? `Check the value for field '${field}'` : 'Check your input data'
+        });
+    }
+}
+export class ConnectionError extends NoormError {
+    constructor(message, originalError) {
+        super(`Database connection failed: ${message}`, {
+            operation: 'connection',
+            suggestion: 'Check your database connection string and ensure the database is running',
+            originalError
+        });
+    }
+}
+/**
+ * Helper function to find similar column names using simple string similarity
+ */
+function findSimilarColumns(columns, target) {
+    const lowerTarget = target.toLowerCase();
+    // First, try exact case-insensitive match
+    const exactMatch = columns.find(col => col.toLowerCase() === lowerTarget);
+    if (exactMatch)
+        return [exactMatch];
+    // Then try substring matches
+    const substringMatches = columns.filter(col => col.toLowerCase().includes(lowerTarget) || lowerTarget.includes(col.toLowerCase()));
+    if (substringMatches.length > 0) {
+        return substringMatches.slice(0, 3); // Return up to 3 matches
+    }
+    // Finally, try simple Levenshtein-like similarity
+    const similarities = columns.map(col => ({
+        name: col,
+        score: calculateSimilarity(lowerTarget, col.toLowerCase())
+    }));
+    return similarities
+        .filter(s => s.score > 0.5) // Only return if similarity > 50%
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 3)
+        .map(s => s.name);
+}
+/**
+ * Simple similarity calculation (Dice coefficient)
+ */
+function calculateSimilarity(str1, str2) {
+    if (str1 === str2)
+        return 1;
+    const bigrams1 = getBigrams(str1);
+    const bigrams2 = getBigrams(str2);
+    const intersection = bigrams1.filter(bigram => bigrams2.includes(bigram));
+    return (2 * intersection.length) / (bigrams1.length + bigrams2.length);
+}
+function getBigrams(str) {
+    const bigrams = [];
+    for (let i = 0; i < str.length - 1; i++) {
+        bigrams.push(str.substring(i, i + 2));
+    }
+    return bigrams;
+}