create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/components/AppTable/engine/table/editing/changeSetSettlement.ts

@@ -0,0 +1,633 @@
+import type { TableEngineMessages } from '../../shared/messages'
+import {
+  deleteTableRowValue,
+  getTableRowValue,
+  setTableRowValue,
+} from '../../shared/row'
+import {
+  createTableRowIndex,
+  type TableRowTreeEntry,
+} from '../../shared/treeRows'
+import type { TableRow } from '../../shared/types'
+import { cloneTableValue } from '../../shared/valueSnapshot'
+import type { TableBaselineStore } from './baselineStore'
+import {
+  indexTableCommitResults,
+  type CreateCommitResult,
+  type RemoveCommitResult,
+  type UpdateCommitResult,
+} from './commitResultIndex'
+import { TABLE_CLIENT_ROW_KEY_PREFIX } from './constants'
+import {
+  createDirtyCellKey as cellKey,
+  type TableDirtyCellIndex,
+} from './dirtyCellIndex'
+import { encodeTableRowKey, isRowKey } from './rowKey'
+import type {
+  ChangeSet,
+  CommitResult,
+  DirtyCell,
+  RowKey,
+  TableChangeSubmission,
+  TableCommitKeyRemap,
+  TableCommitSettlement,
+  VersionConflict,
+} from './types'
+
+export interface PendingCreate<T extends TableRow> {
+  row: T
+  error?: unknown
+}
+
+export interface PendingRemove<T extends TableRow> {
+  row: T
+  error?: unknown
+}
+
+type TableRowIndex<T extends TableRow> = Map<string, TableRowTreeEntry<T>>
+interface FieldGenerationEntry {
+  cellId: string
+  prop: string
+  changedAt: number
+}
+
+interface TableCommitSettlementHost<T extends TableRow> {
+  baseline: TableBaselineStore<T>
+  dirtyCells: TableDirtyCellIndex
+  creates: Map<string, PendingCreate<T>>
+  removes: Map<string, PendingRemove<T>>
+  fieldGenerations: Map<string, number>
+  versionConflicts: Map<string, VersionConflict<T>>
+  getRowKey: (row: T) => RowKey
+  setRowKey: (row: T, rowKey: RowKey) => void
+  getVersion?: (row: T) => string | number | undefined
+  deleteDirtyCells: (rowKey: RowKey) => void
+  invalidateConflictCaches: () => void
+  messages: TableEngineMessages
+}
+
+type PreparedCreate<T extends TableRow> =
+  | {
+      status: 'missing' | 'failed'
+      clientKey: string
+      pending: PendingCreate<T>
+      error: unknown
+    }
+  | {
+      status: 'success'
+      clientKey: string
+      pending: PendingCreate<T>
+      currentEntry?: TableRowTreeEntry<T>
+      current: T
+      item?: CreateCommitResult<T>
+      nextKey: RowKey
+      serverBaseline: T
+      version: string | number | undefined
+      fieldGenerations: readonly FieldGenerationEntry[]
+      rootIndex: number
+    }
+
+type PreparedUpdate<T extends TableRow> =
+  | {
+      status: 'missing'
+      cells: readonly DirtyCell[]
+    }
+  | {
+      status: 'failed'
+      key: string
+      update: ChangeSet<T>['updates'][number]
+      item: UpdateCommitResult<T>
+      cells: readonly DirtyCell[]
+      conflict?: VersionConflict<T>
+    }
+  | {
+      status: 'success'
+      key: string
+      update: ChangeSet<T>['updates'][number]
+      item?: UpdateCommitResult<T>
+      row?: T
+      serverBaseline: T
+      version: string | number | undefined
+      submittedCells?: ReadonlyMap<string, number>
+    }
+
+type PreparedRemove<T extends TableRow> =
+  | {
+      status: 'missing' | 'failed'
+      rowKey: RowKey
+      pending: PendingRemove<T>
+      error: unknown
+    }
+  | { status: 'success'; rowKey: RowKey; key: string }
+
+const indexDirtyCellsByRow = (dirtyCells: TableDirtyCellIndex) => {
+  const result = new Map<string, Array<[string, DirtyCell]>>()
+  for (const entry of dirtyCells) {
+    const key = encodeTableRowKey(entry[1].rowKey)
+    const rowCells = result.get(key)
+    if (rowCells) rowCells.push(entry)
+    else result.set(key, [entry])
+  }
+  return result
+}
+
+/** 一次扫描建立 rowKey→字段世代索引，避免每个新增行重复扫描完整 Map。 */
+const indexFieldGenerationsByRow = (
+  fieldGenerations: ReadonlyMap<string, number>
+) => {
+  const result = new Map<string, FieldGenerationEntry[]>()
+  fieldGenerations.forEach((changedAt, cellId) => {
+    const separator = cellId.indexOf('\u0000')
+    if (separator < 0) return
+    const rowKey = cellId.slice(0, separator)
+    const entry = {
+      cellId,
+      prop: cellId.slice(separator + 1),
+      changedAt,
+    }
+    const entries = result.get(rowKey)
+    if (entries) entries.push(entry)
+    else result.set(rowKey, [entry])
+  })
+  return result
+}
+
+const prepareCreates = <T extends TableRow>(options: {
+  host: TableCommitSettlementHost<T>
+  submission: TableChangeSubmission<T>
+  results: ReadonlyMap<string, CreateCommitResult<T>>
+  rowIndex: TableRowIndex<T>
+  hasExplicitResult: boolean
+  fieldGenerationsByRow: ReadonlyMap<string, readonly FieldGenerationEntry[]>
+}) => {
+  const { host, submission, results, rowIndex, hasExplicitResult } = options
+  const prepared: PreparedCreate<T>[] = []
+  const reservedKeys = new Set(rowIndex.keys())
+  for (const submitted of submission.changeSet.creates) {
+    const clientKey = submitted.clientKey
+    const pending = host.creates.get(clientKey)
+    if (!pending) continue
+    const item = results.get(clientKey)
+    if (hasExplicitResult && !item) {
+      prepared.push({
+        status: 'missing',
+        clientKey,
+        pending,
+        error: host.messages.strMissingCreateResult,
+      })
+      continue
+    }
+    if (item?.success === false) {
+      prepared.push({
+        status: 'failed',
+        clientKey,
+        pending,
+        error: item.error,
+      })
+      continue
+    }
+
+    const currentEntry = rowIndex.get(encodeTableRowKey(clientKey))
+    const current = currentEntry?.row ?? pending.row
+    const serverBaseline = cloneTableValue(submitted.value) as T
+    if (item?.row) Object.assign(serverBaseline, cloneTableValue(item.row))
+    const nextKey =
+      item?.rowKey ?? (item?.row ? host.getRowKey(serverBaseline) : undefined)
+    if (!isRowKey(nextKey)) {
+      throw new Error(
+        `[TableComponent] Commit succeeded for create "${clientKey}" but no valid server rowKey was returned.`
+      )
+    }
+    if (
+      typeof nextKey === 'string' &&
+      nextKey.startsWith(TABLE_CLIENT_ROW_KEY_PREFIX)
+    ) {
+      throw new Error(
+        `[TableComponent] Commit succeeded for create "${clientKey}" but retained a client rowKey.`
+      )
+    }
+    host.setRowKey(serverBaseline, nextKey)
+    if (host.getRowKey(serverBaseline) !== nextKey) {
+      throw new Error(
+        '[TableComponent] A functional rowKey resolver requires the committed row to contain its new server identity.'
+      )
+    }
+    const currentPreview = cloneTableValue(current)
+    if (item?.row) Object.assign(currentPreview, cloneTableValue(item.row))
+    host.setRowKey(currentPreview, nextKey)
+    if (host.getRowKey(currentPreview) !== nextKey) {
+      throw new Error(
+        '[TableComponent] The committed row does not resolve to the returned server rowKey.'
+      )
+    }
+    const encodedNextKey = encodeTableRowKey(nextKey)
+    const encodedClientKey = encodeTableRowKey(clientKey)
+    reservedKeys.delete(encodedClientKey)
+    if (
+      encodedNextKey !== encodedClientKey &&
+      reservedKeys.has(encodedNextKey)
+    ) {
+      throw new Error(
+        `[TableComponent] Server rowKey "${String(nextKey)}" is already used by another row.`
+      )
+    }
+    reservedKeys.add(encodedNextKey)
+
+    prepared.push({
+      status: 'success',
+      clientKey,
+      pending,
+      currentEntry,
+      current,
+      item,
+      nextKey,
+      serverBaseline,
+      version: host.getVersion?.(serverBaseline),
+      fieldGenerations:
+        options.fieldGenerationsByRow.get(encodedClientKey) ?? [],
+      rootIndex: currentEntry?.path.length === 1 ? currentEntry.index : -1,
+    })
+  }
+  return prepared
+}
+
+const prepareConflict = <T extends TableRow>(
+  host: TableCommitSettlementHost<T>,
+  key: string,
+  update: ChangeSet<T>['updates'][number],
+  item: UpdateCommitResult<T>,
+  rowIndex: TableRowIndex<T>,
+  submissionGeneration: number
+): VersionConflict<T> | undefined => {
+  if (!item.conflict) return
+  const serverRow = cloneTableValue(item.conflict.serverRow)
+  const userPatch: Partial<T> = cloneTableValue(update.patch)
+  const row = rowIndex.get(key)?.row
+  if (row) {
+    const prefix = `${key}\u0000`
+    for (const [fieldKey, changedAt] of host.fieldGenerations) {
+      if (!fieldKey.startsWith(prefix) || changedAt <= submissionGeneration)
+        continue
+      const prop = fieldKey.slice(prefix.length)
+      const current = getTableRowValue(row, prop)
+      const server = getTableRowValue(serverRow, prop)
+      if (Object.is(current, server)) deleteTableRowValue(userPatch, prop)
+      else setTableRowValue(userPatch, prop, cloneTableValue(current))
+    }
+  }
+  return {
+    rowKey: update.rowKey,
+    baseVersion: update.baseVersion,
+    serverVersion: item.conflict.serverVersion ?? host.getVersion?.(serverRow),
+    serverRow,
+    userPatch,
+    fields: item.conflict.fields?.map(String) ?? Object.keys(userPatch),
+    code: item.conflict.code,
+    error: item.error,
+  }
+}
+
+const prepareUpdates = <T extends TableRow>(options: {
+  host: TableCommitSettlementHost<T>
+  submission: TableChangeSubmission<T>
+  results: ReadonlyMap<string, UpdateCommitResult<T>>
+  rowIndex: TableRowIndex<T>
+  hasExplicitResult: boolean
+}) => {
+  const prepared: PreparedUpdate<T>[] = []
+  options.submission.changeSet.updates.forEach((update) => {
+    const key = encodeTableRowKey(update.rowKey)
+    const submittedCells = options.submission.cellGenerationsByRow.get(key)
+    const cells = [...(submittedCells?.keys() ?? [])]
+      .map((prop) => options.host.dirtyCells.get(cellKey(update.rowKey, prop)))
+      .filter((cell): cell is DirtyCell => Boolean(cell))
+    const item = options.results.get(key)
+    if (options.hasExplicitResult && !item) {
+      prepared.push({ status: 'missing', cells })
+      return
+    }
+    if (item?.success === false) {
+      prepared.push({
+        status: 'failed',
+        key,
+        update,
+        item,
+        cells,
+        conflict: prepareConflict(
+          options.host,
+          key,
+          update,
+          item,
+          options.rowIndex,
+          options.submission.generation
+        ),
+      })
+      return
+    }
+
+    const row = options.rowIndex.get(key)?.row
+    const previousBaseline = options.host.baseline.getRow(key)
+    const serverBaseline = cloneTableValue(previousBaseline ?? row ?? ({} as T))
+    Object.entries(update.patch).forEach(([prop, value]) =>
+      setTableRowValue(serverBaseline, prop, cloneTableValue(value))
+    )
+    if (item?.row) Object.assign(serverBaseline, cloneTableValue(item.row))
+    prepared.push({
+      status: 'success',
+      key,
+      update,
+      item,
+      row,
+      serverBaseline,
+      version: options.host.getVersion?.(serverBaseline),
+      submittedCells,
+    })
+  })
+  return prepared
+}
+
+const prepareRemoves = <T extends TableRow>(options: {
+  host: TableCommitSettlementHost<T>
+  submission: TableChangeSubmission<T>
+  results: ReadonlyMap<string, RemoveCommitResult<T>>
+  hasExplicitResult: boolean
+}) =>
+  options.submission.changeSet.removes.flatMap(
+    (submitted): PreparedRemove<T>[] => {
+      const rowKey = submitted.rowKey
+      const key = encodeTableRowKey(rowKey)
+      const pending = options.host.removes.get(key)
+      if (!pending) return []
+      const item = options.results.get(key)
+      if (options.hasExplicitResult && !item) {
+        return [
+          {
+            status: 'missing',
+            rowKey,
+            pending,
+            error: options.host.messages.strMissingRemoveResult,
+          },
+        ]
+      }
+      if (item?.success === false) {
+        return [{ status: 'failed', rowKey, pending, error: item.error }]
+      }
+      return [{ status: 'success', rowKey, key }]
+    }
+  )
+
+const setUpdateErrors = (
+  dirtyCells: TableDirtyCellIndex,
+  cells: readonly DirtyCell[],
+  error: unknown
+) => {
+  cells.forEach((cell) => {
+    dirtyCells.upsert(cellKey(cell.rowKey, cell.prop), { ...cell, error })
+  })
+}
+
+const remapCreateFieldGenerations = <T extends TableRow>(
+  host: TableCommitSettlementHost<T>,
+  prepared: Extract<PreparedCreate<T>, { status: 'success' }>,
+  submissionGeneration: number
+) => {
+  prepared.fieldGenerations.forEach(({ cellId, prop, changedAt }) => {
+    host.fieldGenerations.delete(cellId)
+    if (changedAt <= submissionGeneration) return
+    const nextCellKey = cellKey(prepared.nextKey, prop)
+    host.fieldGenerations.set(nextCellKey, changedAt)
+    const original = getTableRowValue(prepared.serverBaseline, prop)
+    const currentValue = getTableRowValue(prepared.current, prop)
+    if (!Object.is(original, currentValue)) {
+      host.dirtyCells.upsert(nextCellKey, {
+        rowKey: prepared.nextKey,
+        prop,
+        original,
+        current: currentValue,
+      })
+    }
+  })
+}
+
+const reconcileDirtyCellsAfterUpdate = <T extends TableRow>(options: {
+  host: TableCommitSettlementHost<T>
+  rowKey: RowKey
+  row: T
+  serverBaseline: T
+  currentRowCells: readonly [string, DirtyCell][]
+  submittedCells?: ReadonlyMap<string, number>
+}) => {
+  const visitedProps = new Set<string>()
+  for (const [cellId, cell] of options.currentRowCells) {
+    visitedProps.add(cell.prop)
+    const submittedAt = options.submittedCells?.get(cell.prop)
+    const currentAt = options.host.fieldGenerations.get(cellId)
+    if (submittedAt !== undefined && currentAt === submittedAt) {
+      options.host.dirtyCells.delete(cellId)
+      options.host.fieldGenerations.delete(cellId)
+      continue
+    }
+    const original = getTableRowValue(options.serverBaseline, cell.prop)
+    const current = getTableRowValue(options.row, cell.prop)
+    if (Object.is(original, current)) {
+      options.host.dirtyCells.delete(cellId)
+      options.host.fieldGenerations.delete(cellId)
+    } else {
+      options.host.dirtyCells.upsert(cellId, {
+        ...cell,
+        original,
+        current,
+        error: undefined,
+      })
+    }
+  }
+  for (const [prop, submittedAt] of options.submittedCells ?? []) {
+    if (visitedProps.has(prop)) continue
+    const cellId = cellKey(options.rowKey, prop)
+    const currentAt = options.host.fieldGenerations.get(cellId)
+    if (currentAt === undefined || currentAt === submittedAt) {
+      options.host.fieldGenerations.delete(cellId)
+      continue
+    }
+    const original = getTableRowValue(options.serverBaseline, prop)
+    const current = getTableRowValue(options.row, prop)
+    if (Object.is(original, current)) {
+      options.host.fieldGenerations.delete(cellId)
+      continue
+    }
+    options.host.dirtyCells.upsert(cellId, {
+      rowKey: options.rowKey,
+      prop,
+      original,
+      current,
+    })
+  }
+}
+
+/**
+ * 先解析所有服务端结果和业务回调，再进入不可异步、不可调用外部函数的提交区。
+ * submission 必须来自请求发出前，禁止在响应阶段捕获实时 tracker 状态。
+ */
+export const applyTableCommitSettlement = <T extends TableRow>(options: {
+  host: TableCommitSettlementHost<T>
+  rows: T[]
+  result: CommitResult<T> | undefined
+  submission: TableChangeSubmission<T>
+}): TableCommitSettlement<T> => {
+  const { host, rows, result, submission } = options
+  const hasExplicitResult = result !== undefined
+  const indexedResults = indexTableCommitResults(submission, result)
+  const createResults = indexedResults.creates
+  const updateResults = indexedResults.updates
+  const removeResults = indexedResults.removes
+  const rowIndex = createTableRowIndex(rows, (row) =>
+    encodeTableRowKey(host.getRowKey(row))
+  )
+  const fieldGenerationsByRow = indexFieldGenerationsByRow(
+    host.fieldGenerations
+  )
+  const creates = prepareCreates({
+    host,
+    submission,
+    results: createResults,
+    rowIndex,
+    hasExplicitResult,
+    fieldGenerationsByRow,
+  })
+  const updates = prepareUpdates({
+    host,
+    submission,
+    results: updateResults,
+    rowIndex,
+    hasExplicitResult,
+  })
+  const removes = prepareRemoves({
+    host,
+    submission,
+    results: removeResults,
+    hasExplicitResult,
+  })
+  const successfulCreates = creates.filter(
+    (item): item is Extract<PreparedCreate<T>, { status: 'success' }> =>
+      item.status === 'success'
+  )
+  const successfulUpdates = updates.filter(
+    (item): item is Extract<PreparedUpdate<T>, { status: 'success' }> =>
+      item.status === 'success'
+  )
+  const successfulRemoves = removes.filter(
+    (item): item is Extract<PreparedRemove<T>, { status: 'success' }> =>
+      item.status === 'success'
+  )
+  const commitBaseline = host.baseline.prepareSettlement({
+    upserts: [
+      ...successfulCreates.map((item) => ({
+        key: encodeTableRowKey(item.nextKey),
+        row: item.serverBaseline,
+        version: item.version,
+        rootIndex: item.rootIndex,
+      })),
+      ...successfulUpdates.flatMap((item) =>
+        item.row
+          ? [
+              {
+                key: item.key,
+                row: item.serverBaseline,
+                version: item.version,
+              },
+            ]
+          : []
+      ),
+    ],
+    removedKeys: new Set(successfulRemoves.map((item) => item.key)),
+    getEncodedKey: (row) => encodeTableRowKey(host.getRowKey(row)),
+  })
+
+  const keyRemaps: TableCommitKeyRemap<T>[] = []
+  creates.forEach((prepared) => {
+    if (prepared.status !== 'success') {
+      prepared.pending.error = prepared.error
+      return
+    }
+    if (prepared.item?.row) {
+      Object.entries(prepared.item.row).forEach(([prop, value]) => {
+        const changedAt = host.fieldGenerations.get(
+          cellKey(prepared.clientKey, prop)
+        )
+        if (!changedAt || changedAt <= submission.generation) {
+          setTableRowValue(prepared.current, prop, value)
+        }
+      })
+    }
+    host.setRowKey(prepared.current, prepared.nextKey)
+    host.creates.delete(prepared.clientKey)
+    remapCreateFieldGenerations(host, prepared, submission.generation)
+    keyRemaps.push({
+      previousKey: prepared.clientKey,
+      nextKey: prepared.nextKey,
+      row: prepared.current,
+    })
+  })
+
+  const dirtyCellsByRow = indexDirtyCellsByRow(host.dirtyCells)
+  updates.forEach((prepared) => {
+    if (prepared.status === 'missing') {
+      setUpdateErrors(
+        host.dirtyCells,
+        prepared.cells,
+        host.messages.strMissingUpdateResult
+      )
+      return
+    }
+    if (prepared.status === 'failed') {
+      if (prepared.conflict) {
+        host.versionConflicts.set(prepared.key, prepared.conflict)
+        host.invalidateConflictCaches()
+      }
+      prepared.cells.forEach((cell) => {
+        host.dirtyCells.upsert(cellKey(cell.rowKey, cell.prop), {
+          ...cell,
+          error:
+            prepared.item.fieldErrors?.[cell.prop] ??
+            prepared.item.error ??
+            (prepared.item.conflict
+              ? host.messages.strServerDataUpdated
+              : host.messages.strSaveFailed),
+        })
+      })
+      return
+    }
+    if (prepared.row && prepared.item?.row) {
+      Object.entries(prepared.item.row).forEach(([prop, value]) => {
+        const changedAt = host.fieldGenerations.get(
+          cellKey(prepared.update.rowKey, prop)
+        )
+        if (!changedAt || changedAt <= submission.generation) {
+          setTableRowValue(prepared.row!, prop, value)
+        }
+      })
+    }
+    if (host.versionConflicts.delete(prepared.key))
+      host.invalidateConflictCaches()
+    if (!prepared.row) return
+    reconcileDirtyCellsAfterUpdate({
+      host,
+      rowKey: prepared.update.rowKey,
+      row: prepared.row,
+      serverBaseline: prepared.serverBaseline,
+      currentRowCells: dirtyCellsByRow.get(prepared.key) ?? [],
+      submittedCells: prepared.submittedCells,
+    })
+  })
+
+  removes.forEach((prepared) => {
+    if (prepared.status !== 'success') {
+      prepared.pending.error = prepared.error
+      return
+    }
+    host.removes.delete(prepared.key)
+    host.deleteDirtyCells(prepared.rowKey)
+  })
+  commitBaseline()
+  return { rows, keyRemaps: Object.freeze(keyRemaps) }
+}

package/template/src/components/AppTable/engine/table/editing/commitResultIndex.ts

@@ -0,0 +1,75 @@
+import type { TableRow } from '../../shared/types'
+import { encodeTableRowKey } from './rowKey'
+import type { CommitResult, TableChangeSubmission } from './types'
+
+export type CreateCommitResult<T extends TableRow> = NonNullable<
+  CommitResult<T>['creates']
+>[number]
+export type UpdateCommitResult<T extends TableRow> = NonNullable<
+  CommitResult<T>['updates']
+>[number]
+export type RemoveCommitResult<T extends TableRow> = NonNullable<
+  CommitResult<T>['removes']
+>[number]
+
+const indexCommitResults = <T>(options: {
+  items: readonly T[] | undefined
+  getKey: (item: T) => string
+  submittedKeys: ReadonlySet<string>
+  label: string
+}) => {
+  const result = new Map<string, T>()
+  for (const item of options.items ?? []) {
+    const key = options.getKey(item)
+    if (!options.submittedKeys.has(key)) {
+      throw new Error(
+        `[TableComponent] Server returned an unknown ${options.label} result "${key}".`
+      )
+    }
+    if (result.has(key)) {
+      throw new Error(
+        `[TableComponent] Server returned duplicate ${options.label} results for "${key}".`
+      )
+    }
+    result.set(key, item)
+  }
+  return result
+}
+
+/** 在提交任何状态前验证服务端结果只包含本次 submission 的唯一事务项。 */
+export const indexTableCommitResults = <T extends TableRow>(
+  submission: TableChangeSubmission<T>,
+  result: CommitResult<T> | undefined
+) => {
+  const submitted = {
+    creates: new Set(
+      submission.changeSet.creates.map((item) => item.clientKey)
+    ),
+    updates: new Set(
+      submission.changeSet.updates.map((item) => encodeTableRowKey(item.rowKey))
+    ),
+    removes: new Set(
+      submission.changeSet.removes.map((item) => encodeTableRowKey(item.rowKey))
+    ),
+  }
+  return {
+    creates: indexCommitResults({
+      items: result?.creates,
+      getKey: (item) => item.clientKey,
+      submittedKeys: submitted.creates,
+      label: 'create',
+    }),
+    updates: indexCommitResults({
+      items: result?.updates,
+      getKey: (item) => encodeTableRowKey(item.rowKey),
+      submittedKeys: submitted.updates,
+      label: 'update',
+    }),
+    removes: indexCommitResults({
+      items: result?.removes,
+      getKey: (item) => encodeTableRowKey(item.rowKey),
+      submittedKeys: submitted.removes,
+      label: 'remove',
+    }),
+  }
+}