@remix-run/data-table 0.1.0 → 0.2.0

package/src/lib/references.ts

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

package/src/lib/sql-helpers.ts

@@ -0,0 +1,146 @@
+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 function isDataManipulationOperation(
+  operation: DataManipulationOperation | DataMigrationOperation,
+): operation is DataManipulationOperation {
+  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: string): string {
+  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: Record<string, unknown>[]): string[] {
+  let columns: string[] = []
+  let seen = new Set<string>()
+
+  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: string, quoteIdentifier: QuoteIdentifier): string {
+  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: TableRef, quoteIdentifier: QuoteIdentifier): string {
+  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: unknown,
+  options?: {
+    booleansAsIntegers?: boolean
+  },
+): string {
+  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/src/lib/sql.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
@@ -9,8 +12,16 @@ 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 function sql(strings: TemplateStringsArray, ...values: unknown[]): SqlStatement {
   let text = ''
@@ -42,9 +53,9 @@ export function sql(strings: TemplateStringsArray, ...values: unknown[]): SqlSta
 }
 
 /**
- * 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: unknown): value is SqlStatement {
   if (typeof value !== 'object' || value === null) {
@@ -58,9 +69,15 @@ export 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 function rawSql(text: string, values: unknown[] = []): SqlStatement {
   return { text, values }