first draft of dataframeV2

Author: severo

src/helpers/dataframeV2.ts

@@ -0,0 +1,99 @@
+import { Cells } from './row.js'
+import { OrderBy } from './sort'
+import { CustomEventTarget, createEventTarget } from './typedEventTarget'
+
+// Map of event type -> detail
+// Starting with a single event, required in Iceberg
+// TODO(SL): shall we force lowercase event type? https://developer.mozilla.org/en-US/docs/Web/API/Element/MozMousePixelScroll_event is a counter-example (but deprecated).
+interface DataFrameEvents {
+  'dataframe:numrowschange': { numRows: number };
+}
+
+/**
+ * DataFrameV2 is an interface for a data structure that represents a table of data.
+ *
+ * It can mutate its data, and a table can subscribe to changes using the eventTarget.
+ */
+export interface DataFrameV2 {
+  numRows: number
+  header: string[]
+
+  // undefined means pending, ResolvedValue is a boxed value type (so we can distinguish undefined from pending)
+  // getCell does NOT initiate a fetch, it just returns resolved data
+  getCell({ row, column, orderBy }: {row: number, column: string, orderBy?: OrderBy}): ResolvedValue | undefined
+
+  // initiate fetches for row/column data:
+  fetch({ rowStart, rowEnd, columns, orderBy }: { rowStart: number, rowEnd: number, columns: string[], orderBy?: OrderBy }): CancellableJob
+
+  // emits events, defined in DataFrameEvents
+  eventTarget: CustomEventTarget<DataFrameEvents>
+}
+
+interface ResolvedValue {
+  value: any
+}
+
+interface CancellableJob {
+  // table can call cancel when a user scrolls out of view. dataframe implementer can choose to ignore, de-queue, or cancel in flight fetches.
+  cancel(): void
+}
+
+export function arrayDataFrame(data: Cells[]): DataFrameV2 {
+  const eventTarget = createEventTarget<DataFrameEvents>()
+  // eventTarget can be used as follows:
+  //
+  // listen to an event:
+  // eventTarget.addEventListener('dataframe:numrowschange', (event) => {
+  //   console.log('Number of rows changed:', event.detail.numRows)
+  // })
+  //
+  // publish an event:
+  // eventTarget.dispatchEvent(new CustomEvent('dataframe:numrowschange', { detail: { numRows: 42 } }))
+
+  function fetch({ orderBy }: { rowStart: number, rowEnd: number, columns: string[], orderBy?: OrderBy }) {
+    if (orderBy && orderBy.length > 0) {
+      throw new Error('Sorting is not implemented.')
+    }
+    return {
+      cancel: () => {
+        // No-op for static data
+      },
+    }
+  }
+  if (!(0 in data)) {
+    return {
+      numRows: 0,
+      header: [],
+      getCell: () => undefined,
+      fetch,
+      eventTarget,
+    }
+  }
+
+  const header = Object.keys(data[0])
+
+  return {
+    numRows: data.length,
+    header,
+    getCell: ({ row, column, orderBy }) => {
+      if (orderBy && orderBy.length > 0) {
+        throw new Error('Sorting is not implemented.')
+      }
+      const cells = data[row]
+      if (!cells) {
+        throw new Error(`Invalid row index: ${row}`)
+      }
+      if (!header.includes(column)) {
+        throw new Error(`Invalid column: ${column}`)
+      }
+      if (!(column in cells)) {
+        throw new Error(`Column "${column}" not found in row ${row}`)
+      }
+      // Return a resolved value (which might be undefined as well)
+      return { value: data[row] }
+      // Note that this function never returns undefined (meaning pending cell), because the data is static.
+    },
+    fetch,
+    eventTarget,
+  }
+}

src/helpers/typedEventTarget.ts

@@ -0,0 +1,52 @@
+// EventTarget is not a generic type in TypeScript.
+// We use the code adapted from https://github.com/microsoft/TypeScript/issues/28357#issuecomment-2310186394
+// to add type safety.
+
+/**
+ * Type-safe event listener and dispatch signatures for the custom events
+ * defined in `TDetails`.
+ */
+export interface CustomEventTarget<TDetails> {
+  addEventListener<TType extends keyof TDetails>(
+    type: TType,
+
+    listener: (ev: CustomEvent<TDetails[TType]>) => any,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+
+  removeEventListener<TType extends keyof TDetails>(
+    type: TType,
+
+    listener: (ev: CustomEvent<TDetails[TType]>) => any,
+    options?: boolean | EventListenerOptions,
+  ): void;
+
+  dispatchEvent<TType extends keyof TDetails>(
+    ev: _TypedCustomEvent<TDetails, TType>,
+  ): void;
+}
+
+/**
+ * Internal declaration for the `typeof` trick below.
+ * Never actually implemented.
+ */
+declare class _TypedCustomEvent<
+  TDetails,
+  TType extends keyof TDetails,
+> extends CustomEvent<TDetails[TType]> {
+  constructor(
+    type: TType,
+    eventInitDict: { detail: TDetails[TType] } & EventInit,
+  );
+}
+
+/**
+ * Typed custom event (technically a typed alias of `CustomEvent`).
+ * Use with `CustomEventTarget.dispatchEvent` to infer `detail` types
+ * automatically.
+ */
+export const TypedCustomEvent = CustomEvent as typeof _TypedCustomEvent
+
+export function createEventTarget<TDetails>(): CustomEventTarget<TDetails> {
+  return new EventTarget() as CustomEventTarget<TDetails>
+}