@remix-run/data-table 0.0.0 → 0.2.0

package/src/lib/errors.ts

@@ -0,0 +1,119 @@
+/**
+ * Base error for all `data-table` failures.
+ */
+export class DataTableError extends Error {
+  /**
+   * Stable error code identifying the failure category.
+   */
+  code: string
+
+  /**
+   * Optional structured metadata attached to the failure.
+   */
+  metadata?: Record<string, unknown>
+
+  constructor(
+    message: string,
+    options?: {
+      code?: string
+      cause?: unknown
+      metadata?: Record<string, unknown>
+    },
+  ) {
+    super(message, { cause: options?.cause })
+    this.name = 'DataTableError'
+    this.code = options?.code ?? 'DATA_TABLE_ERROR'
+    this.metadata = options?.metadata
+  }
+}
+
+/**
+ * Thrown when input data fails schema validation.
+ */
+export class DataTableValidationError extends DataTableError {
+  /**
+   * Validation issues reported by the schema validator.
+   */
+  issues: ReadonlyArray<unknown>
+
+  constructor(
+    message: string,
+    issues: ReadonlyArray<unknown>,
+    options?: {
+      cause?: unknown
+      metadata?: Record<string, unknown>
+    },
+  ) {
+    super(message, {
+      code: 'DATA_TABLE_VALIDATION_ERROR',
+      cause: options?.cause,
+      metadata: options?.metadata,
+    })
+
+    this.name = 'DataTableValidationError'
+    this.issues = issues
+  }
+}
+
+/**
+ * Thrown when a query is invalid for the current builder state.
+ */
+export class DataTableQueryError extends DataTableError {
+  constructor(
+    message: string,
+    options?: {
+      cause?: unknown
+      metadata?: Record<string, unknown>
+    },
+  ) {
+    super(message, {
+      code: 'DATA_TABLE_QUERY_ERROR',
+      cause: options?.cause,
+      metadata: options?.metadata,
+    })
+
+    this.name = 'DataTableQueryError'
+  }
+}
+
+/**
+ * Thrown when adapter execution fails.
+ */
+export class DataTableAdapterError extends DataTableError {
+  constructor(
+    message: string,
+    options?: {
+      cause?: unknown
+      metadata?: Record<string, unknown>
+    },
+  ) {
+    super(message, {
+      code: 'DATA_TABLE_ADAPTER_ERROR',
+      cause: options?.cause,
+      metadata: options?.metadata,
+    })
+
+    this.name = 'DataTableAdapterError'
+  }
+}
+
+/**
+ * Thrown when a database constraint is violated.
+ */
+export class DataTableConstraintError extends DataTableError {
+  constructor(
+    message: string,
+    options?: {
+      cause?: unknown
+      metadata?: Record<string, unknown>
+    },
+  ) {
+    super(message, {
+      code: 'DATA_TABLE_CONSTRAINT_ERROR',
+      cause: options?.cause,
+      metadata: options?.metadata,
+    })
+
+    this.name = 'DataTableConstraintError'
+  }
+}

package/src/lib/inflection.ts

@@ -0,0 +1,69 @@
+const IRREGULAR_SINGULAR_FORMS: Record<string, string> = {
+  people: 'person',
+  men: 'man',
+  women: 'woman',
+  children: 'child',
+  teeth: 'tooth',
+  feet: 'foot',
+  geese: 'goose',
+  mice: 'mouse',
+  data: 'datum',
+  media: 'medium',
+  indices: 'index',
+  vertices: 'vertex',
+  analyses: 'analysis',
+  statuses: 'status',
+  categories: 'category',
+  companies: 'company',
+  addresses: 'address',
+}
+
+export function singularize(word: string): string {
+  let lower = word.toLowerCase()
+
+  if (IRREGULAR_SINGULAR_FORMS[lower]) {
+    return preserveCase(word, IRREGULAR_SINGULAR_FORMS[lower])
+  }
+
+  if (lower.endsWith('ies') && lower.length > 3) {
+    return preserveCase(word, word.slice(0, -3) + 'y')
+  }
+
+  if (lower.endsWith('sses') || lower.endsWith('shes') || lower.endsWith('ches')) {
+    return preserveCase(word, word.slice(0, -2))
+  }
+
+  if (lower.endsWith('xes') || lower.endsWith('zes')) {
+    return preserveCase(word, word.slice(0, -2))
+  }
+
+  if (lower.endsWith('s') && !lower.endsWith('ss')) {
+    return preserveCase(word, word.slice(0, -1))
+  }
+
+  return word
+}
+
+export function inferForeignKey(tableName: string): string {
+  let segments = tableName.split('_')
+  let tail = segments.pop() ?? tableName
+  let singularTail = singularize(tail)
+
+  if (segments.length === 0) {
+    return singularTail + '_id'
+  }
+
+  return [...segments, singularTail + '_id'].join('_')
+}
+
+function preserveCase(source: string, replacement: string): string {
+  if (source.length === 0) {
+    return replacement
+  }
+
+  if (source[0] === source[0].toUpperCase()) {
+    return replacement[0].toUpperCase() + replacement.slice(1)
+  }
+
+  return replacement
+}

package/src/lib/migrations/filename.ts

@@ -0,0 +1,25 @@
+const migrationFilenamePattern = /^(\d{14})_(.+)\.(?:m?ts|m?js|cts|cjs)$/
+
+/**
+ * Parses a migration filename into `{ id, name }`.
+ *
+ * Expected format: `YYYYMMDDHHmmss_name.(ts|js|mts|mjs|cts|cjs)`.
+ * @param filename Migration file basename.
+ * @returns Parsed migration id and name.
+ */
+export function parseMigrationFilename(filename: string): { id: string; name: string } {
+  let match = filename.match(migrationFilenamePattern)
+
+  if (!match) {
+    throw new Error(
+      'Invalid migration filename "' +
+        filename +
+        '". Expected format YYYYMMDDHHmmss_name.ts (or .js/.mts/.mjs/.cts/.cjs)',
+    )
+  }
+
+  return {
+    id: match[1],
+    name: match[2],
+  }
+}

package/src/lib/migrations/helpers.ts

@@ -0,0 +1,108 @@
+import type { TableRef } from '../adapter.ts'
+import type { IndexColumns, KeyColumns } from '../migrations.ts'
+
+export function toTableRef(name: string): TableRef {
+  let segments = name.split('.')
+
+  if (segments.length === 1) {
+    return { name }
+  }
+
+  return {
+    schema: segments[0],
+    name: segments.slice(1).join('.'),
+  }
+}
+
+export function normalizeIndexColumns(columns: IndexColumns): string[] {
+  return normalizeKeyColumns(columns)
+}
+
+export function normalizeKeyColumns(columns: KeyColumns): string[] {
+  if (Array.isArray(columns)) {
+    return [...columns]
+  }
+
+  return [columns]
+}
+
+function normalizeNamePart(value: string): string {
+  let normalized = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+
+  if (normalized.length === 0) {
+    return 'item'
+  }
+
+  return normalized
+}
+
+function tableNamePart(table: TableRef): string {
+  if (table.schema) {
+    return normalizeNamePart(table.schema + '_' + table.name)
+  }
+
+  return normalizeNamePart(table.name)
+}
+
+function hashString(value: string): number {
+  let hash = 5381
+
+  for (let index = 0; index < value.length; index++) {
+    hash = ((hash << 5) + hash) ^ value.charCodeAt(index)
+  }
+
+  return hash >>> 0
+}
+
+function withNameLimit(name: string): string {
+  let limit = 63
+
+  if (name.length <= limit) {
+    return name
+  }
+
+  let suffix = hashString(name).toString(36).padStart(8, '0').slice(0, 8)
+  return name.slice(0, limit - 9) + '_' + suffix
+}
+
+function columnsNamePart(columns: string[]): string {
+  return columns.map((column) => normalizeNamePart(column)).join('_')
+}
+
+export function createPrimaryKeyName(table: TableRef): string {
+  return withNameLimit(tableNamePart(table) + '_pk')
+}
+
+export function createUniqueName(table: TableRef, columns: string[]): string {
+  return withNameLimit(tableNamePart(table) + '_' + columnsNamePart(columns) + '_uq')
+}
+
+export function createForeignKeyName(
+  table: TableRef,
+  columns: string[],
+  references: TableRef,
+  referenceColumns: string[],
+): string {
+  let base =
+    tableNamePart(table) +
+    '_' +
+    columnsNamePart(columns) +
+    '_' +
+    tableNamePart(references) +
+    '_' +
+    columnsNamePart(referenceColumns) +
+    '_fk'
+  return withNameLimit(base)
+}
+
+export function createCheckName(table: TableRef, expression: string): string {
+  let suffix = hashString(expression).toString(36)
+  return withNameLimit(tableNamePart(table) + '_chk_' + suffix)
+}
+
+export function createIndexName(table: TableRef, columns: string[]): string {
+  return withNameLimit(tableNamePart(table) + '_' + columnsNamePart(columns) + '_idx')
+}

package/src/lib/migrations/journal-store.ts

@@ -0,0 +1,122 @@
+import type { DatabaseAdapter, TransactionToken } from '../adapter.ts'
+import { rawSql } from '../sql.ts'
+import type { MigrationDescriptor, MigrationJournalRow } from '../migrations.ts'
+
+export function normalizeChecksum(migration: MigrationDescriptor): string {
+  if (migration.checksum) {
+    return migration.checksum
+  }
+
+  return migration.id + ':' + migration.name
+}
+
+export async function ensureMigrationJournal(
+  adapter: DatabaseAdapter,
+  tableName: string,
+): Promise<void> {
+  await adapter.migrate({
+    operation: {
+      kind: 'createTable',
+      table: { name: tableName },
+      ifNotExists: true,
+      columns: {
+        id: { type: 'varchar', length: 64, nullable: false, primaryKey: true },
+        name: { type: 'varchar', length: 255, nullable: false },
+        checksum: { type: 'varchar', length: 128, nullable: false },
+        batch: { type: 'integer', nullable: false },
+        applied_at: { type: 'timestamp', nullable: false, default: { kind: 'now' } },
+      },
+    },
+  })
+}
+
+export async function hasMigrationJournal(
+  adapter: DatabaseAdapter,
+  tableName: string,
+): Promise<boolean> {
+  try {
+    await adapter.execute({
+      operation: {
+        kind: 'raw',
+        sql: rawSql('select 1 from ' + tableName + ' limit 1'),
+      },
+    })
+
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function loadJournalRows(
+  adapter: DatabaseAdapter,
+  tableName: string,
+): Promise<MigrationJournalRow[]> {
+  let result = await adapter.execute({
+    operation: {
+      kind: 'raw',
+      sql: rawSql(
+        'select id, name, checksum, batch, applied_at from ' + tableName + ' order by id asc',
+      ),
+    },
+  })
+
+  let rows = result.rows ?? []
+
+  return rows.map((row) => ({
+    id: String(row.id),
+    name: String(row.name),
+    checksum: String(row.checksum),
+    batch: Number(row.batch),
+    appliedAt: new Date(String(row.applied_at)),
+  }))
+}
+
+export async function insertJournalRow(
+  adapter: DatabaseAdapter,
+  tableName: string,
+  row: {
+    id: string
+    name: string
+    checksum: string
+    batch: number
+  },
+  transaction?: TransactionToken,
+): Promise<void> {
+  await adapter.execute({
+    operation: {
+      kind: 'raw',
+      sql: rawSql('insert into ' + tableName + ' (id, name, checksum, batch) values (?, ?, ?, ?)', [
+        row.id,
+        row.name,
+        row.checksum,
+        row.batch,
+      ]),
+    },
+    transaction,
+  })
+}
+
+export async function deleteJournalRow(
+  adapter: DatabaseAdapter,
+  tableName: string,
+  id: string,
+  transaction?: TransactionToken,
+): Promise<void> {
+  await adapter.execute({
+    operation: {
+      kind: 'raw',
+      sql: rawSql('delete from ' + tableName + ' where id = ?', [id]),
+    },
+    transaction,
+  })
+}
+
+export function getBatch(rows: MigrationJournalRow[]): number {
+  if (rows.length === 0) {
+    return 1
+  }
+
+  let max = Math.max(...rows.map((row) => row.batch))
+  return max + 1
+}

package/src/lib/migrations/registry.ts

@@ -0,0 +1,62 @@
+import type { MigrationDescriptor, MigrationRegistry } from '../migrations.ts'
+
+/**
+ * Returns a new array of migrations ordered by migration id.
+ * @param migrations Migration descriptors to sort.
+ * @returns A newly sorted migration descriptor array.
+ */
+export function sortMigrations(migrations: MigrationDescriptor[]): MigrationDescriptor[] {
+  return [...migrations].sort((left, right) => left.id.localeCompare(right.id))
+}
+
+/**
+ * Resolves a migration source into a sorted migration list.
+ * @param input Migration list or registry.
+ * @returns A sorted migration descriptor list.
+ */
+export function resolveMigrations(
+  input: MigrationDescriptor[] | MigrationRegistry,
+): MigrationDescriptor[] {
+  if (Array.isArray(input)) {
+    return sortMigrations(input)
+  }
+
+  return input.list()
+}
+
+/**
+ * Creates an in-memory migration registry.
+ * @param initial Optional initial migration list.
+ * @returns A migration registry with duplicate-id protection.
+ * @example
+ * ```ts
+ * import { createMigrationRegistry } from 'remix/data-table/migrations'
+ *
+ * let registry = createMigrationRegistry()
+ * registry.register({ id, name, migration })
+ * ```
+ */
+export function createMigrationRegistry(initial: MigrationDescriptor[] = []): MigrationRegistry {
+  let migrations = new Map<string, MigrationDescriptor>()
+
+  for (let migration of initial) {
+    if (migrations.has(migration.id)) {
+      throw new Error('Duplicate migration id: ' + migration.id)
+    }
+
+    migrations.set(migration.id, migration)
+  }
+
+  return {
+    register(migration: MigrationDescriptor) {
+      if (migrations.has(migration.id)) {
+        throw new Error('Duplicate migration id: ' + migration.id)
+      }
+
+      migrations.set(migration.id, migration)
+    },
+    list() {
+      return sortMigrations(Array.from(migrations.values()))
+    },
+  }
+}