@remix-run/data-table 0.0.0 → 0.2.0

package/src/lib/references.ts

@@ -0,0 +1,78 @@
+/**
+ * Symbol key used to store non-enumerable table metadata.
+ */
+export const tableMetadataKey = Symbol('data-table.tableMetadata')
+
+/**
+ * Symbol key used to store non-enumerable column metadata.
+ */
+export const columnMetadataKey = Symbol('data-table.columnMetadata')
+
+type UnknownTableMetadata<
+  name extends string = string,
+  columns extends Record<string, unknown> = Record<string, unknown>,
+  primaryKey extends readonly string[] = readonly string[],
+  timestamps = unknown,
+> = {
+  name: name
+  columns: columns
+  primaryKey: primaryKey
+  timestamps: timestamps
+}
+
+export type TableMetadataLike<
+  name extends string = string,
+  columns extends Record<string, unknown> = Record<string, unknown>,
+  primaryKey extends readonly string[] = readonly string[],
+  timestamps = unknown,
+> = {
+  [tableMetadataKey]: UnknownTableMetadata<name, columns, primaryKey, timestamps>
+}
+
+export type ColumnReferenceLike<qualifiedName extends string = string> = {
+  kind: 'column'
+  [columnMetadataKey]: {
+    tableName: string
+    columnName: string
+    qualifiedName: qualifiedName
+  }
+}
+
+export type ColumnInput<qualifiedName extends string = string> =
+  | qualifiedName
+  | ColumnReferenceLike<qualifiedName>
+
+export type NormalizeColumnInput<input> =
+  input extends ColumnReferenceLike<infer qualifiedName> ? qualifiedName : input
+
+/**
+ * Returns `true` when a value is a `data-table` column reference.
+ * @param value Value to inspect.
+ * @returns Whether the value is a column reference object.
+ */
+export function isColumnReference(value: unknown): value is ColumnReferenceLike {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  if (!('kind' in value) || (value as { kind?: unknown }).kind !== 'column') {
+    return false
+  }
+
+  return columnMetadataKey in (value as object)
+}
+
+/**
+ * Normalizes string/column-reference inputs to a qualified column name.
+ * @param input Column name or column reference.
+ * @returns The normalized qualified column name.
+ */
+export function normalizeColumnInput<input extends string | ColumnReferenceLike>(
+  input: input,
+): NormalizeColumnInput<input> {
+  if (typeof input === 'string') {
+    return input as NormalizeColumnInput<input>
+  }
+
+  return input[columnMetadataKey].qualifiedName as NormalizeColumnInput<input>
+}

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

@@ -0,0 +1,84 @@
+/**
+ * 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
+  values: unknown[]
+}
+
+/**
+ * Tagged-template helper for building parameterized SQL statements.
+ * @param strings Template string parts.
+ * @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 = ''
+  let parameters: unknown[] = []
+  let index = 0
+
+  while (index < strings.length) {
+    text += strings[index]
+
+    if (index < values.length) {
+      let value = values[index]
+
+      if (isSqlStatement(value)) {
+        text += value.text
+        parameters.push(...value.values)
+      } else {
+        text += '?'
+        parameters.push(value)
+      }
+    }
+
+    index += 1
+  }
+
+  return {
+    text,
+    values: parameters,
+  }
+}
+
+/**
+ * Returns `true` when a value matches the {@link SqlStatement} shape.
+ * @param value Value to inspect.
+ * @returns Whether the value is a {@link SqlStatement} object.
+ */
+export function isSqlStatement(value: unknown): value is SqlStatement {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  let statement = value as { text?: unknown; values?: unknown }
+
+  return typeof statement.text === 'string' && Array.isArray(statement.values)
+}
+
+/**
+ * Creates a SQL statement from raw text and values.
+ * @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 }
+}