@remix-run/data-table 0.1.0 → 0.2.1

package/dist/lib/query.js

@@ -0,0 +1,401 @@
+import { DataTableQueryError, DataTableValidationError } from "./errors.js";
+import { normalizeWhereInput } from "./operators.js";
+import { normalizeColumnInput } from "./references.js";
+import { getTableColumns, getTableName } from "./table.js";
+export const bindQueryRuntime = Symbol('bindQueryRuntime');
+export const querySnapshot = Symbol('querySnapshot');
+export class Query {
+    #table;
+    #state;
+    #plan;
+    #runtime;
+    constructor(table) {
+        this.#table = table;
+        this.#state = createInitialQueryState();
+        this.#plan = { kind: 'all' };
+    }
+    static #createInternal(table, state, plan, runtime) {
+        let output = new Query(table);
+        output.#state = cloneQueryState(state);
+        output.#plan = cloneQueryPlan(plan);
+        output.#runtime = runtime;
+        return output;
+    }
+    select(...input) {
+        if (input.length === 1 &&
+            typeof input[0] === 'object' &&
+            input[0] !== null &&
+            !Array.isArray(input[0])) {
+            let selection = input[0];
+            let aliases = Object.keys(selection);
+            let select = aliases.map((alias) => ({
+                column: normalizeColumnInput(selection[alias]),
+                alias,
+            }));
+            return this.#clone({ select });
+        }
+        let columns = input;
+        return this.#clone({
+            select: columns.map((column) => ({ column, alias: column })),
+        });
+    }
+    distinct(value = true) {
+        return this.#clone({ distinct: value });
+    }
+    where(input) {
+        let predicate = normalizeWhereInput(input);
+        let normalizedPredicate = normalizePredicateValues(predicate, createPredicateColumnResolver([this.#table, ...this.#state.joins.map((join) => join.table)]));
+        return this.#clone({
+            where: [...this.#state.where, normalizedPredicate],
+        });
+    }
+    having(input) {
+        let predicate = normalizeWhereInput(input);
+        let normalizedPredicate = normalizePredicateValues(predicate, createPredicateColumnResolver([this.#table, ...this.#state.joins.map((join) => join.table)]));
+        return this.#clone({
+            having: [...this.#state.having, normalizedPredicate],
+        });
+    }
+    join(target, on, type = 'inner') {
+        let normalizedOn = normalizePredicateValues(on, createPredicateColumnResolver([
+            this.#table,
+            ...this.#state.joins.map((join) => join.table),
+            target,
+        ]));
+        return this.#clone({
+            joins: [...this.#state.joins, { type, table: target, on: normalizedOn }],
+        });
+    }
+    leftJoin(target, on) {
+        return this.join(target, on, 'left');
+    }
+    rightJoin(target, on) {
+        return this.join(target, on, 'right');
+    }
+    orderBy(column, direction = 'asc') {
+        return this.#clone({
+            orderBy: [...this.#state.orderBy, { column: normalizeColumnInput(column), direction }],
+        });
+    }
+    groupBy(...columns) {
+        return this.#clone({
+            groupBy: [...this.#state.groupBy, ...columns.map((column) => normalizeColumnInput(column))],
+        });
+    }
+    limit(value) {
+        return this.#clone({ limit: value });
+    }
+    offset(value) {
+        return this.#clone({ offset: value });
+    }
+    with(relations) {
+        return this.#clone({
+            with: {
+                ...this.#state.with,
+                ...relations,
+            },
+        });
+    }
+    all() {
+        return this.#boundRuntime().exec(this);
+    }
+    first() {
+        return this.#resolveTerminal({ kind: 'first' });
+    }
+    find(value) {
+        return this.#resolveTerminal({ kind: 'find', value });
+    }
+    count() {
+        return this.#resolveTerminal({ kind: 'count' });
+    }
+    exists() {
+        return this.#resolveTerminal({ kind: 'exists' });
+    }
+    insert(values, options) {
+        assertWriteState(this.#state, 'insert', {
+            where: false,
+            orderBy: false,
+            limit: false,
+            offset: false,
+        });
+        return this.#resolveTerminal({ kind: 'insert', values, options });
+    }
+    insertMany(values, options) {
+        assertWriteState(this.#state, 'insertMany', {
+            where: false,
+            orderBy: false,
+            limit: false,
+            offset: false,
+        });
+        return this.#resolveTerminal({ kind: 'insertMany', values, options });
+    }
+    update(changes, options) {
+        assertWriteState(this.#state, 'update', {
+            where: true,
+            orderBy: true,
+            limit: true,
+            offset: true,
+        });
+        return this.#resolveTerminal({ kind: 'update', changes, options });
+    }
+    delete(options) {
+        assertWriteState(this.#state, 'delete', {
+            where: true,
+            orderBy: true,
+            limit: true,
+            offset: true,
+        });
+        return this.#resolveTerminal({ kind: 'delete', options });
+    }
+    upsert(values, options) {
+        assertWriteState(this.#state, 'upsert', {
+            where: false,
+            orderBy: false,
+            limit: false,
+            offset: false,
+        });
+        return this.#resolveTerminal({ kind: 'upsert', values, options });
+    }
+    [querySnapshot]() {
+        return this.#snapshot();
+    }
+    #resolveTerminal(plan) {
+        let next = this.#withPlan(plan);
+        return (this.#runtime ? this.#runtime.exec(next) : next);
+    }
+    [bindQueryRuntime](runtime) {
+        return Query.#createInternal(this.#table, this.#state, this.#plan, runtime);
+    }
+    #clone(patch) {
+        return Query.#createInternal(this.#table, {
+            select: patch.select ?? cloneSelection(this.#state.select),
+            distinct: patch.distinct ?? this.#state.distinct,
+            joins: patch.joins ? [...patch.joins] : [...this.#state.joins],
+            where: patch.where ? [...patch.where] : [...this.#state.where],
+            groupBy: patch.groupBy ? [...patch.groupBy] : [...this.#state.groupBy],
+            having: patch.having ? [...patch.having] : [...this.#state.having],
+            orderBy: patch.orderBy ? [...patch.orderBy] : [...this.#state.orderBy],
+            limit: patch.limit === undefined ? this.#state.limit : patch.limit,
+            offset: patch.offset === undefined ? this.#state.offset : patch.offset,
+            with: patch.with ? { ...patch.with } : { ...this.#state.with },
+        }, this.#plan, this.#runtime);
+    }
+    #withPlan(plan) {
+        return Query.#createInternal(this.#table, this.#state, plan, this.#runtime);
+    }
+    #snapshot() {
+        return {
+            table: this.#table,
+            state: cloneQueryState(this.#state),
+            plan: cloneQueryPlan(this.#plan),
+        };
+    }
+    #boundRuntime() {
+        if (!this.#runtime) {
+            throw new DataTableQueryError('Use db.exec(query) to execute an unbound Query');
+        }
+        return this.#runtime;
+    }
+}
+export function query(table) {
+    return new Query(table);
+}
+export function cloneQueryState(state) {
+    return {
+        select: cloneSelection(state.select),
+        distinct: state.distinct,
+        joins: [...state.joins],
+        where: [...state.where],
+        groupBy: [...state.groupBy],
+        having: [...state.having],
+        orderBy: [...state.orderBy],
+        limit: state.limit,
+        offset: state.offset,
+        with: { ...state.with },
+    };
+}
+function createInitialQueryState() {
+    return {
+        select: '*',
+        distinct: false,
+        joins: [],
+        where: [],
+        groupBy: [],
+        having: [],
+        orderBy: [],
+        with: {},
+    };
+}
+function cloneQueryPlan(plan) {
+    switch (plan.kind) {
+        case 'all':
+            return { kind: 'all' };
+        case 'first':
+            return { kind: 'first' };
+        case 'find':
+            return {
+                kind: 'find',
+                value: clonePrimaryKeyValue(plan.value),
+            };
+        case 'count':
+            return { kind: 'count' };
+        case 'exists':
+            return { kind: 'exists' };
+        case 'insert':
+            return {
+                kind: 'insert',
+                values: { ...plan.values },
+                options: plan.options ? { ...plan.options } : undefined,
+            };
+        case 'insertMany':
+            return {
+                kind: 'insertMany',
+                values: plan.values.map((value) => ({ ...value })),
+                options: plan.options ? { ...plan.options } : undefined,
+            };
+        case 'update':
+            return {
+                kind: 'update',
+                changes: { ...plan.changes },
+                options: plan.options ? { ...plan.options } : undefined,
+            };
+        case 'delete':
+            return {
+                kind: 'delete',
+                options: plan.options ? { ...plan.options } : undefined,
+            };
+        case 'upsert':
+            return {
+                kind: 'upsert',
+                values: { ...plan.values },
+                options: plan.options
+                    ? {
+                        ...plan.options,
+                        conflictTarget: plan.options.conflictTarget
+                            ? [...plan.options.conflictTarget]
+                            : undefined,
+                        update: plan.options.update ? { ...plan.options.update } : undefined,
+                    }
+                    : undefined,
+            };
+    }
+}
+function clonePrimaryKeyValue(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return value;
+    }
+    return { ...value };
+}
+function cloneSelection(selection) {
+    if (selection === '*') {
+        return '*';
+    }
+    return selection.map((column) => ({ ...column }));
+}
+function assertWriteState(state, operation, policy) {
+    let unsupported = [];
+    if (state.select !== '*')
+        unsupported.push('select()');
+    if (state.distinct)
+        unsupported.push('distinct()');
+    if (state.joins.length > 0)
+        unsupported.push('join()');
+    if (state.groupBy.length > 0)
+        unsupported.push('groupBy()');
+    if (state.having.length > 0)
+        unsupported.push('having()');
+    if (Object.keys(state.with).length > 0)
+        unsupported.push('with()');
+    if (!policy.where && state.where.length > 0)
+        unsupported.push('where()');
+    if (!policy.orderBy && state.orderBy.length > 0)
+        unsupported.push('orderBy()');
+    if (!policy.limit && state.limit !== undefined)
+        unsupported.push('limit()');
+    if (!policy.offset && state.offset !== undefined)
+        unsupported.push('offset()');
+    if (unsupported.length > 0) {
+        throw new DataTableQueryError(operation + '() does not support these query modifiers: ' + unsupported.join(', '));
+    }
+}
+function createPredicateColumnResolver(tables) {
+    let qualifiedColumns = new Map();
+    let unqualifiedColumns = new Map();
+    let ambiguousColumns = new Set();
+    for (let table of tables) {
+        let tableColumns = getTableColumns(table);
+        let tableName = getTableName(table);
+        for (let columnName in tableColumns) {
+            if (!Object.prototype.hasOwnProperty.call(tableColumns, columnName)) {
+                continue;
+            }
+            let resolvedColumn = {
+                tableName,
+                columnName,
+            };
+            qualifiedColumns.set(tableName + '.' + columnName, resolvedColumn);
+            if (ambiguousColumns.has(columnName)) {
+                continue;
+            }
+            if (unqualifiedColumns.has(columnName)) {
+                unqualifiedColumns.delete(columnName);
+                ambiguousColumns.add(columnName);
+                continue;
+            }
+            unqualifiedColumns.set(columnName, resolvedColumn);
+        }
+    }
+    return function resolveColumn(column) {
+        let qualified = qualifiedColumns.get(column);
+        if (qualified)
+            return qualified;
+        if (column.includes('.')) {
+            throw new DataTableQueryError('Unknown predicate column "' + column + '"');
+        }
+        if (ambiguousColumns.has(column)) {
+            throw new DataTableQueryError('Ambiguous predicate column "' + column + '". Use a qualified column name');
+        }
+        let unqualified = unqualifiedColumns.get(column);
+        if (!unqualified) {
+            throw new DataTableQueryError('Unknown predicate column "' + column + '"');
+        }
+        return unqualified;
+    };
+}
+function normalizePredicateValues(predicate, resolveColumn) {
+    if (predicate.type === 'comparison') {
+        let column = resolveColumn(predicate.column);
+        if (predicate.valueType === 'column') {
+            resolveColumn(predicate.value);
+            return predicate;
+        }
+        if (predicate.operator === 'in' || predicate.operator === 'notIn') {
+            if (!Array.isArray(predicate.value)) {
+                throw new DataTableValidationError('Invalid filter value for column "' +
+                    column.columnName +
+                    '" in table "' +
+                    column.tableName +
+                    '"', [{ message: 'Expected an array value for "' + predicate.operator + '" predicate' }], {
+                    metadata: {
+                        table: column.tableName,
+                        column: column.columnName,
+                    },
+                });
+            }
+            return predicate;
+        }
+        return predicate;
+    }
+    if (predicate.type === 'between') {
+        resolveColumn(predicate.column);
+        return predicate;
+    }
+    if (predicate.type === 'null') {
+        resolveColumn(predicate.column);
+        return predicate;
+    }
+    return {
+        ...predicate,
+        predicates: predicate.predicates.map((child) => normalizePredicateValues(child, resolveColumn)),
+    };
+}

package/dist/lib/references.d.ts

@@ -21,7 +21,6 @@ export type ColumnReferenceLike<qualifiedName extends string = string> = {
         tableName: string;
         columnName: string;
         qualifiedName: qualifiedName;
-        schema: unknown;
     };
 };
 export type ColumnInput<qualifiedName extends string = string> = qualifiedName | ColumnReferenceLike<qualifiedName>;

package/dist/lib/references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../../src/lib/references.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,gBAAgB,eAAqC,CAAA;AAElE;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAAsC,CAAA;AAEpE,KAAK,oBAAoB,CACvB,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,SAAS,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,EACxD,UAAU,GAAG,OAAO,IAClB;IACF,IAAI,EAAE,IAAI,CAAA;IACV,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,UAAU,CAAA;IACtB,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,iBAAiB,CAC3B,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,SAAS,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,EACxD,UAAU,GAAG,OAAO,IAClB;IACF,CAAC,gBAAgB,CAAC,EAAE,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,CAAA;CAChF,CAAA;AAED,MAAM,MAAM,mBAAmB,CAAC,aAAa,SAAS,MAAM,GAAG,MAAM,IAAI;IACvE,IAAI,EAAE,QAAQ,CAAA;IACd,CAAC,iBAAiB,CAAC,EAAE;QACnB,SAAS,EAAE,MAAM,CAAA;QACjB,UAAU,EAAE,MAAM,CAAA;QAClB,aAAa,EAAE,aAAa,CAAA;QAC5B,MAAM,EAAE,OAAO,CAAA;KAChB,CAAA;CACF,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,aAAa,SAAS,MAAM,GAAG,MAAM,IACzD,aAAa,GACb,mBAAmB,CAAC,aAAa,CAAC,CAAA;AAEtC,MAAM,MAAM,oBAAoB,CAAC,KAAK,IACpC,KAAK,SAAS,mBAAmB,CAAC,MAAM,aAAa,CAAC,GAAG,aAAa,GAAG,KAAK,CAAA;AAEhF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAU9E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,SAAS,MAAM,GAAG,mBAAmB,EAC7E,KAAK,EAAE,KAAK,GACX,oBAAoB,CAAC,KAAK,CAAC,CAM7B"}
+{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../../src/lib/references.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,gBAAgB,eAAqC,CAAA;AAElE;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAAsC,CAAA;AAEpE,KAAK,oBAAoB,CACvB,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,SAAS,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,EACxD,UAAU,GAAG,OAAO,IAClB;IACF,IAAI,EAAE,IAAI,CAAA;IACV,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,UAAU,CAAA;IACtB,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,iBAAiB,CAC3B,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,UAAU,SAAS,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,EACxD,UAAU,GAAG,OAAO,IAClB;IACF,CAAC,gBAAgB,CAAC,EAAE,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,CAAA;CAChF,CAAA;AAED,MAAM,MAAM,mBAAmB,CAAC,aAAa,SAAS,MAAM,GAAG,MAAM,IAAI;IACvE,IAAI,EAAE,QAAQ,CAAA;IACd,CAAC,iBAAiB,CAAC,EAAE;QACnB,SAAS,EAAE,MAAM,CAAA;QACjB,UAAU,EAAE,MAAM,CAAA;QAClB,aAAa,EAAE,aAAa,CAAA;KAC7B,CAAA;CACF,CAAA;AAED,MAAM,MAAM,WAAW,CAAC,aAAa,SAAS,MAAM,GAAG,MAAM,IACzD,aAAa,GACb,mBAAmB,CAAC,aAAa,CAAC,CAAA;AAEtC,MAAM,MAAM,oBAAoB,CAAC,KAAK,IACpC,KAAK,SAAS,mBAAmB,CAAC,MAAM,aAAa,CAAC,GAAG,aAAa,GAAG,KAAK,CAAA;AAEhF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAU9E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,SAAS,MAAM,GAAG,mBAAmB,EAC7E,KAAK,EAAE,KAAK,GACX,oBAAoB,CAAC,KAAK,CAAC,CAM7B"}

package/dist/lib/sql-helpers.d.ts

@@ -0,0 +1,50 @@
+import type { DataManipulationOperation, DataMigrationOperation, TableRef } from './adapter.ts';
+/**
+ * Function used to quote SQL identifiers for a dialect.
+ */
+export type QuoteIdentifier = (value: string) => string;
+/**
+ * Type guard that narrows an operation to the data-manipulation union.
+ * @param operation Operation to inspect.
+ * @returns `true` when the operation is a data-manipulation operation.
+ */
+export declare function isDataManipulationOperation(operation: DataManipulationOperation | DataMigrationOperation): operation is DataManipulationOperation;
+/**
+ * Normalizes an arbitrary join type string into `inner`, `left`, or `right`.
+ * @param type Input join type.
+ * @returns Normalized join type.
+ */
+export declare function normalizeJoinType(type: string): string;
+/**
+ * Returns stable column order from the union of keys in the provided rows.
+ * @param rows Row objects to scan for keys.
+ * @returns Deduplicated key list in encounter order.
+ */
+export declare function collectColumns(rows: Record<string, unknown>[]): string[];
+/**
+ * Quotes each segment of a dotted identifier path.
+ *
+ * Wildcard segments (`*`) are preserved.
+ * @param path Dotted path to quote.
+ * @param quoteIdentifier Dialect-specific identifier quote function.
+ * @returns Quoted path string.
+ */
+export declare function quotePath(path: string, quoteIdentifier: QuoteIdentifier): string;
+/**
+ * Quotes a `{ schema?, name }` table reference using a dialect quote function.
+ * @param table Table reference to quote.
+ * @param quoteIdentifier Dialect-specific identifier quote function.
+ * @returns Quoted table reference.
+ */
+export declare function quoteTableRef(table: TableRef, quoteIdentifier: QuoteIdentifier): string;
+/**
+ * Converts a JavaScript value into a SQL literal string.
+ * @param value Value to serialize.
+ * @param options Serialization options.
+ * @param options.booleansAsIntegers When `true`, booleans render as `1`/`0`.
+ * @returns SQL literal text.
+ */
+export declare function quoteLiteral(value: unknown, options?: {
+    booleansAsIntegers?: boolean;
+}): string;
+//# sourceMappingURL=sql-helpers.d.ts.map

package/dist/lib/sql-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-helpers.d.ts","sourceRoot":"","sources":["../../src/lib/sql-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAE/F;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;AAEvD;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,yBAAyB,GAAG,sBAAsB,GAC5D,SAAS,IAAI,yBAAyB,CAYxC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUtD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,EAAE,CAoBxE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,GAAG,MAAM,CAehF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,eAAe,GAAG,MAAM,CAMvF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;IACR,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B,GACA,MAAM,CAsBR"}

package/dist/lib/sql-helpers.js

@@ -0,0 +1,111 @@
+/**
+ * Type guard that narrows an operation to the data-manipulation union.
+ * @param operation Operation to inspect.
+ * @returns `true` when the operation is a data-manipulation operation.
+ */
+export function isDataManipulationOperation(operation) {
+    return (operation.kind === 'select' ||
+        operation.kind === 'count' ||
+        operation.kind === 'exists' ||
+        operation.kind === 'insert' ||
+        operation.kind === 'insertMany' ||
+        operation.kind === 'update' ||
+        operation.kind === 'delete' ||
+        operation.kind === 'upsert' ||
+        operation.kind === 'raw');
+}
+/**
+ * Normalizes an arbitrary join type string into `inner`, `left`, or `right`.
+ * @param type Input join type.
+ * @returns Normalized join type.
+ */
+export function normalizeJoinType(type) {
+    if (type === 'left') {
+        return 'left';
+    }
+    if (type === 'right') {
+        return 'right';
+    }
+    return 'inner';
+}
+/**
+ * Returns stable column order from the union of keys in the provided rows.
+ * @param rows Row objects to scan for keys.
+ * @returns Deduplicated key list in encounter order.
+ */
+export function collectColumns(rows) {
+    let columns = [];
+    let seen = new Set();
+    for (let row of rows) {
+        for (let key in row) {
+            if (!Object.prototype.hasOwnProperty.call(row, key)) {
+                continue;
+            }
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            columns.push(key);
+        }
+    }
+    return columns;
+}
+/**
+ * Quotes each segment of a dotted identifier path.
+ *
+ * Wildcard segments (`*`) are preserved.
+ * @param path Dotted path to quote.
+ * @param quoteIdentifier Dialect-specific identifier quote function.
+ * @returns Quoted path string.
+ */
+export function quotePath(path, quoteIdentifier) {
+    if (path === '*') {
+        return '*';
+    }
+    return path
+        .split('.')
+        .map((segment) => {
+        if (segment === '*') {
+            return '*';
+        }
+        return quoteIdentifier(segment);
+    })
+        .join('.');
+}
+/**
+ * Quotes a `{ schema?, name }` table reference using a dialect quote function.
+ * @param table Table reference to quote.
+ * @param quoteIdentifier Dialect-specific identifier quote function.
+ * @returns Quoted table reference.
+ */
+export function quoteTableRef(table, quoteIdentifier) {
+    if (table.schema) {
+        return quoteIdentifier(table.schema) + '.' + quoteIdentifier(table.name);
+    }
+    return quoteIdentifier(table.name);
+}
+/**
+ * Converts a JavaScript value into a SQL literal string.
+ * @param value Value to serialize.
+ * @param options Serialization options.
+ * @param options.booleansAsIntegers When `true`, booleans render as `1`/`0`.
+ * @returns SQL literal text.
+ */
+export function quoteLiteral(value, options) {
+    if (value === null) {
+        return 'null';
+    }
+    if (typeof value === 'number' || typeof value === 'bigint') {
+        return String(value);
+    }
+    if (typeof value === 'boolean') {
+        if (options?.booleansAsIntegers) {
+            return value ? '1' : '0';
+        }
+        return value ? 'true' : 'false';
+    }
+    if (value instanceof Date) {
+        return quoteLiteral(value.toISOString(), options);
+    }
+    return "'" + String(value).replace(/'/g, "''") + "'";
+}

package/dist/lib/sql.d.ts

@@ -1,5 +1,8 @@
 /**
- * Parameterized SQL payload with positional `?` placeholders.
+ * Parameterized SQL payload.
+ *
+ * The `text` may contain positional placeholders (`?`) or dialect-native
+ * placeholders (for example `$1`, `$2`) depending on compiler stage.
  */
 export type SqlStatement = {
     text: string;
@@ -8,21 +11,35 @@ export type SqlStatement = {
 /**
  * Tagged-template helper for building parameterized SQL statements.
  * @param strings Template string parts.
- * @param values Interpolated values or nested `SqlStatement` values.
- * @returns A normalized SQL statement.
+ * @param values Interpolated values or nested {@link SqlStatement} values.
+ * @returns A normalized {@link SqlStatement}.
+ * @example
+ * ```ts
+ * import { sql } from 'remix/data-table'
+ *
+ * let email = 'user@example.com'
+ * let statement = sql`select * from users where email = ${email}`
+ * // => { text: 'select * from users where email = ?', values: ['user@example.com'] }
+ * ```
  */
 export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): SqlStatement;
 /**
- * Returns `true` when a value matches the `SqlStatement` shape.
+ * Returns `true` when a value matches the {@link SqlStatement} shape.
  * @param value Value to inspect.
- * @returns Whether the value is a SQL statement object.
+ * @returns Whether the value is a {@link SqlStatement} object.
  */
 export declare function isSqlStatement(value: unknown): value is SqlStatement;
 /**
  * Creates a SQL statement from raw text and values.
- * @param text SQL text containing `?` placeholders.
+ * @param text SQL text containing placeholders expected by the target adapter.
  * @param values Placeholder values.
  * @returns A normalized SQL statement.
+ * @example
+ * ```ts
+ * import { rawSql } from 'remix/data-table'
+ *
+ * let statement = rawSql('select * from users where id = ?', [1])
+ * ```
  */
 export declare function rawSql(text: string, values?: unknown[]): SqlStatement;
 //# sourceMappingURL=sql.d.ts.map

package/dist/lib/sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/lib/sql.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,EAAE,CAAA;CAClB,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,YAAY,CA2BrF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAQpE;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,YAAY,CAEzE"}
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/lib/sql.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,EAAE,CAAA;CAClB,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,YAAY,CA2BrF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAQpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,YAAY,CAEzE"}

package/dist/lib/sql.js

@@ -1,8 +1,16 @@
 /**
  * Tagged-template helper for building parameterized SQL statements.
  * @param strings Template string parts.
- * @param values Interpolated values or nested `SqlStatement` values.
- * @returns A normalized SQL statement.
+ * @param values Interpolated values or nested {@link SqlStatement} values.
+ * @returns A normalized {@link SqlStatement}.
+ * @example
+ * ```ts
+ * import { sql } from 'remix/data-table'
+ *
+ * let email = 'user@example.com'
+ * let statement = sql`select * from users where email = ${email}`
+ * // => { text: 'select * from users where email = ?', values: ['user@example.com'] }
+ * ```
  */
 export function sql(strings, ...values) {
     let text = '';
@@ -29,9 +37,9 @@ export function sql(strings, ...values) {
     };
 }
 /**
- * Returns `true` when a value matches the `SqlStatement` shape.
+ * Returns `true` when a value matches the {@link SqlStatement} shape.
  * @param value Value to inspect.
- * @returns Whether the value is a SQL statement object.
+ * @returns Whether the value is a {@link SqlStatement} object.
  */
 export function isSqlStatement(value) {
     if (typeof value !== 'object' || value === null) {
@@ -42,9 +50,15 @@ export function isSqlStatement(value) {
 }
 /**
  * Creates a SQL statement from raw text and values.
- * @param text SQL text containing `?` placeholders.
+ * @param text SQL text containing placeholders expected by the target adapter.
  * @param values Placeholder values.
  * @returns A normalized SQL statement.
+ * @example
+ * ```ts
+ * import { rawSql } from 'remix/data-table'
+ *
+ * let statement = rawSql('select * from users where id = ?', [1])
+ * ```
  */
 export function rawSql(text, values = []) {
     return { text, values };