@pilotiq/pilotiq 0.1.0

package/src/sessionFilters.test.ts

@@ -0,0 +1,352 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  listFiltersKey,
+  lastTabKey,
+  readPersistedListQuery,
+  writePersistedListQuery,
+  readPersistedLastTab,
+  writePersistedLastTab,
+  encodePersistedQuery,
+} from './sessionFilters.js'
+
+/**
+ * Minimal SessionInstance stand-in — the same shape the rudder
+ * `SessionInstance.get / put` exposes. Tracks `put` calls so the no-op
+ * deep-equal short-circuit can be asserted.
+ */
+function makeSession() {
+  const data: Record<string, unknown> = {}
+  const puts: Array<[string, unknown]> = []
+  return {
+    data,
+    puts,
+    get<T>(key: string, fallback?: T): T | undefined {
+      return (key in data ? data[key] : fallback) as T | undefined
+    },
+    put(key: string, value: unknown): void {
+      data[key] = value
+      puts.push([key, value])
+    },
+  }
+}
+
+describe('listFiltersKey', () => {
+  it('joins prefix + basePath + slug + slot:<tab> with single colons', () => {
+    assert.equal(listFiltersKey('/admin', 'posts'),         'pilotiq:filters:/admin:posts:slot:')
+    assert.equal(listFiltersKey('/admin', 'posts', ''),     'pilotiq:filters:/admin:posts:slot:')
+    assert.equal(listFiltersKey('/admin', 'posts', 'drafts'), 'pilotiq:filters:/admin:posts:slot:drafts')
+  })
+
+  it('different slugs produce distinct keys', () => {
+    assert.notEqual(listFiltersKey('/admin', 'posts'), listFiltersKey('/admin', 'users'))
+  })
+
+  it('different tabs on the same slug produce distinct keys', () => {
+    assert.notEqual(
+      listFiltersKey('/admin', 'posts', 'drafts'),
+      listFiltersKey('/admin', 'posts', 'published'),
+    )
+  })
+})
+
+describe('lastTabKey', () => {
+  it('joins prefix + basePath + slug + lastTab', () => {
+    assert.equal(lastTabKey('/admin', 'posts'), 'pilotiq:filters:/admin:posts:lastTab')
+  })
+
+  it('does not collide with any slot key', () => {
+    // The slot namespace is `:slot:<tab>`; lastTab key is `:lastTab`. The
+    // `:slot:` infix prevents a tab literally named `lastTab` from clobbering.
+    assert.notEqual(lastTabKey('/admin', 'posts'), listFiltersKey('/admin', 'posts', 'lastTab'))
+  })
+})
+
+describe('writePersistedListQuery', () => {
+  it('stores filter values and reserved-but-persistable keys', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, {
+      status: 'draft',
+      group:  'authorId',
+      search: 'foo',
+      sort:   'createdAt:desc',
+      perPage: '25',
+    })
+    assert.deepEqual(session.data[key], {
+      status: 'draft', group: 'authorId', search: 'foo', sort: 'createdAt:desc', perPage: '25',
+    })
+  })
+
+  it('skips page (resets to 1 on restore) and tab (separate state)', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, {
+      status: 'draft',
+      page:   '3',
+      tab:    'published',
+    })
+    assert.deepEqual(session.data[key], { status: 'draft' })
+  })
+
+  it('skips Tier-3 prefixed page keys (Table.queryStringIdentifier)', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, {
+      orders_status: 'draft',
+      orders_page:   '3',
+      page:          '4',  // bare also dropped
+    })
+    assert.deepEqual(session.data[key], { orders_status: 'draft' })
+  })
+
+  it('preserves empty-string values (explicit-clear marker)', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, { status: '' })
+    assert.deepEqual(session.data[key], { status: '' })
+  })
+
+  it('skips non-string values defensively', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, {
+      status: 'draft',
+      junk:   42 as unknown as string,
+      blob:   { x: 1 } as unknown as string,
+    })
+    assert.deepEqual(session.data[key], { status: 'draft' })
+  })
+
+  it('no-ops when the slice deep-equals the stored value', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, { status: 'draft' })
+    writePersistedListQuery(req, key, { status: 'draft' })
+    assert.equal(session.puts.length, 1)
+  })
+
+  it('writes when the stored value is a different shape', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, { status: 'draft' })
+    writePersistedListQuery(req, key, { status: 'draft', sort: 'id:asc' })
+    assert.equal(session.puts.length, 2)
+  })
+
+  it('writes the empty slice (clears prior state)', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, { status: 'draft' })
+    writePersistedListQuery(req, key, {})
+    assert.deepEqual(session.data[key], {})
+  })
+
+  it('no-ops silently when no session is on req', () => {
+    assert.doesNotThrow(() =>
+      writePersistedListQuery({}, listFiltersKey('/admin', 'posts'), { status: 'draft' }),
+    )
+  })
+
+  it('no-ops silently on undefined req', () => {
+    assert.doesNotThrow(() =>
+      writePersistedListQuery(undefined, listFiltersKey('/admin', 'posts'), { status: 'draft' }),
+    )
+  })
+
+  it('per-tab keying — same slug, different tabs land in distinct slots', () => {
+    const session = makeSession()
+    const req = { session }
+    writePersistedListQuery(req, listFiltersKey('/admin', 'posts', 'drafts'),    { status: 'draft' })
+    writePersistedListQuery(req, listFiltersKey('/admin', 'posts', 'published'), { sort: 'title:asc' })
+    assert.deepEqual(session.data[listFiltersKey('/admin', 'posts', 'drafts')],    { status: 'draft' })
+    assert.deepEqual(session.data[listFiltersKey('/admin', 'posts', 'published')], { sort: 'title:asc' })
+  })
+})
+
+describe('readPersistedListQuery', () => {
+  it('returns the stored slice', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    writePersistedListQuery(req, key, { status: 'draft' })
+    assert.deepEqual(readPersistedListQuery(req, key), { status: 'draft' })
+  })
+
+  it('returns undefined when nothing was stored', () => {
+    const session = makeSession()
+    const req = { session }
+    assert.equal(readPersistedListQuery(req, listFiltersKey('/admin', 'posts')), undefined)
+  })
+
+  it('returns undefined when stored value is the wrong shape', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    session.data[key] = ['not', 'a', 'map']
+    assert.equal(readPersistedListQuery(req, key), undefined)
+    session.data[key] = 'string'
+    assert.equal(readPersistedListQuery(req, key), undefined)
+  })
+
+  it('drops non-string entries defensively', () => {
+    const session = makeSession()
+    const req = { session }
+    const key = listFiltersKey('/admin', 'posts')
+    session.data[key] = { status: 'draft', n: 42, m: { x: 1 } }
+    assert.deepEqual(readPersistedListQuery(req, key), { status: 'draft' })
+  })
+
+  it('returns undefined when no session is mounted', () => {
+    assert.equal(readPersistedListQuery({}, listFiltersKey('/admin', 'posts')), undefined)
+  })
+
+  it('per-tab keying — reading one tab\'s slot does not pull in another\'s', () => {
+    const session = makeSession()
+    const req = { session }
+    writePersistedListQuery(req, listFiltersKey('/admin', 'posts', 'drafts'),    { status: 'draft' })
+    writePersistedListQuery(req, listFiltersKey('/admin', 'posts', 'published'), { sort: 'title:asc' })
+    assert.deepEqual(readPersistedListQuery(req, listFiltersKey('/admin', 'posts', 'drafts')),    { status: 'draft' })
+    assert.deepEqual(readPersistedListQuery(req, listFiltersKey('/admin', 'posts', 'published')), { sort: 'title:asc' })
+  })
+})
+
+describe('lastTab pointer', () => {
+  it('writePersistedLastTab + readPersistedLastTab round-trip', () => {
+    const session = makeSession()
+    const req = { session }
+    writePersistedLastTab(req, '/admin', 'posts', 'drafts')
+    assert.equal(readPersistedLastTab(req, '/admin', 'posts'), 'drafts')
+  })
+
+  it('returns undefined when no pointer was written', () => {
+    const session = makeSession()
+    const req = { session }
+    assert.equal(readPersistedLastTab(req, '/admin', 'posts'), undefined)
+  })
+
+  it('overwrites on subsequent writes', () => {
+    const session = makeSession()
+    const req = { session }
+    writePersistedLastTab(req, '/admin', 'posts', 'drafts')
+    writePersistedLastTab(req, '/admin', 'posts', 'published')
+    assert.equal(readPersistedLastTab(req, '/admin', 'posts'), 'published')
+  })
+
+  it('no-ops when the pointer is unchanged', () => {
+    const session = makeSession()
+    const req = { session }
+    writePersistedLastTab(req, '/admin', 'posts', 'drafts')
+    writePersistedLastTab(req, '/admin', 'posts', 'drafts')
+    assert.equal(session.puts.length, 1)
+  })
+
+  it('persists empty string explicitly (user moved off a named tab back to default)', () => {
+    const session = makeSession()
+    const req = { session }
+    writePersistedLastTab(req, '/admin', 'posts', 'drafts')
+    writePersistedLastTab(req, '/admin', 'posts', '')
+    assert.equal(readPersistedLastTab(req, '/admin', 'posts'), '')
+  })
+
+  it('returns undefined when stored value is non-string', () => {
+    const session = makeSession()
+    const req = { session }
+    session.data[lastTabKey('/admin', 'posts')] = 42 as unknown
+    assert.equal(readPersistedLastTab(req, '/admin', 'posts'), undefined)
+  })
+
+  it('no-ops silently when no session is mounted', () => {
+    assert.doesNotThrow(() => writePersistedLastTab({}, '/admin', 'posts', 'drafts'))
+    assert.equal(readPersistedLastTab({}, '/admin', 'posts'), undefined)
+  })
+})
+
+describe('encodePersistedQuery', () => {
+  it('builds a stable URLSearchParams string', () => {
+    const qs = encodePersistedQuery({ status: 'draft', sort: 'id:desc' })
+    const params = new URLSearchParams(qs)
+    assert.equal(params.get('status'), 'draft')
+    assert.equal(params.get('sort'),   'id:desc')
+  })
+
+  it('drops empty-value entries (explicit-clear markers do not redirect)', () => {
+    assert.equal(encodePersistedQuery({ status: '' }), '')
+  })
+
+  it('returns an empty string for an empty slice and no tab', () => {
+    assert.equal(encodePersistedQuery({}), '')
+    assert.equal(encodePersistedQuery({}, ''), '')
+  })
+
+  it('prepends ?tab=<name> when tab arg is non-empty', () => {
+    const qs = encodePersistedQuery({ status: 'draft' }, 'published')
+    const params = new URLSearchParams(qs)
+    assert.equal(params.get('tab'),    'published')
+    assert.equal(params.get('status'), 'draft')
+  })
+
+  it('emits ?tab=<name> alone when slice is empty', () => {
+    const qs = encodePersistedQuery({}, 'published')
+    const params = new URLSearchParams(qs)
+    assert.equal(params.get('tab'), 'published')
+    assert.equal(params.size, 1)
+  })
+
+  it('omits tab when empty (default-tab restore needs no tab param)', () => {
+    const qs = encodePersistedQuery({ status: 'draft' }, '')
+    const params = new URLSearchParams(qs)
+    assert.equal(params.get('tab'),    null)
+    assert.equal(params.get('status'), 'draft')
+  })
+})
+
+describe('per-tab persistence — full round-trip', () => {
+  it('two tabs each retain their own filter slice across switches', () => {
+    const session = makeSession()
+    const req = { session }
+    // User visits ?tab=drafts&status=draft → slot:drafts + lastTab=drafts.
+    writePersistedListQuery(req, listFiltersKey('/admin', 'posts', 'drafts'), { tab: 'drafts', status: 'draft' })
+    writePersistedLastTab(req, '/admin', 'posts', 'drafts')
+    // Then ?tab=published&sort=title:asc → slot:published + lastTab=published.
+    writePersistedListQuery(req, listFiltersKey('/admin', 'posts', 'published'), { tab: 'published', sort: 'title:asc' })
+    writePersistedLastTab(req, '/admin', 'posts', 'published')
+    // Reads remain isolated per tab.
+    assert.deepEqual(readPersistedListQuery(req, listFiltersKey('/admin', 'posts', 'drafts')),    { status: 'draft' })
+    assert.deepEqual(readPersistedListQuery(req, listFiltersKey('/admin', 'posts', 'published')), { sort: 'title:asc' })
+    // lastTab pointer reflects the most recent visit.
+    assert.equal(readPersistedLastTab(req, '/admin', 'posts'), 'published')
+  })
+
+  it('bare-visit restore = readLastTab → readSlot(lastTab) → encode(slot, lastTab)', () => {
+    const session = makeSession()
+    const req = { session }
+    writePersistedListQuery(req, listFiltersKey('/admin', 'posts', 'drafts'), { tab: 'drafts', status: 'draft' })
+    writePersistedLastTab(req, '/admin', 'posts', 'drafts')
+
+    // Simulating the bare-visit restore in routes.ts.
+    const restoreTab = readPersistedLastTab(req, '/admin', 'posts') ?? ''
+    const slot       = readPersistedListQuery(req, listFiltersKey('/admin', 'posts', restoreTab)) ?? {}
+    const qs         = encodePersistedQuery(slot, restoreTab)
+    const params     = new URLSearchParams(qs)
+    assert.equal(params.get('tab'),    'drafts')
+    assert.equal(params.get('status'), 'draft')
+  })
+
+  it('bare-visit restore on a never-visited resource returns no qs (no redirect)', () => {
+    const session = makeSession()
+    const req = { session }
+    const restoreTab = readPersistedLastTab(req, '/admin', 'posts') ?? ''
+    const slot       = readPersistedListQuery(req, listFiltersKey('/admin', 'posts', restoreTab))
+    assert.equal(slot, undefined)
+  })
+})

package/src/sessionFilters.ts

@@ -0,0 +1,133 @@
+// Duck-typed adapter over `@rudderjs/session` — pilotiq doesn't peer
+// depend, so helpers no-op silently when no session is mounted on the
+// request.
+
+const PREFIX = 'pilotiq:filters:'
+
+const EXCLUDED_KEYS = new Set(['page', 'tab'])
+
+// Heuristic also catches `<prefix>_page` from `Table.queryStringIdentifier`.
+// A filter literally named `something_page` would be dropped too, but
+// that's an unusual filter name.
+function isPageKey(key: string): boolean {
+  if (key === 'page') return true
+  return key.endsWith('_page')
+}
+
+interface StorableSession {
+  get<T>(key: string, fallback?: T): T | undefined
+  put(key: string, value: unknown): void
+}
+
+function getSession(req: unknown): StorableSession | undefined {
+  if (!req || typeof req !== 'object') return undefined
+  const session = (req as { session?: unknown }).session
+  if (!session || typeof session !== 'object') return undefined
+  const s = session as Record<string, unknown>
+  if (typeof s['get'] !== 'function' || typeof s['put'] !== 'function') return undefined
+  return session as StorableSession
+}
+
+// Per-tab slot key. `tab === ''` is the "no tab" / "default tab" slot —
+// resources without ListTabs always store under it. Tab name comes from
+// `?tab=<name>` verbatim — keying by the URL value (not by the tab's
+// "default" status) keeps writers + readers symmetric without the
+// route handler having to know the schema's default-tab name.
+export function listFiltersKey(basePath: string, slug: string, tab: string = ''): string {
+  return `${PREFIX}${basePath}:${slug}:slot:${tab}`
+}
+
+// Pointer to whichever tab the user was last on. Read on bare-URL visits
+// to decide which slot to restore — without it, bare visits would always
+// restore the no-tab slot (a regression vs v1, where one slot held
+// whatever tab+filters combo the user last applied).
+export function lastTabKey(basePath: string, slug: string): string {
+  return `${PREFIX}${basePath}:${slug}:lastTab`
+}
+
+export function readPersistedListQuery(
+  req: unknown,
+  key: string,
+): Record<string, string> | undefined {
+  const session = getSession(req)
+  if (!session) return undefined
+  const v = session.get<unknown>(key)
+  if (!v || typeof v !== 'object' || Array.isArray(v)) return undefined
+  // Filter out non-string values defensively — a malformed cookie that
+  // round-tripped through some other writer shouldn't crash the page.
+  const out: Record<string, string> = {}
+  for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+    if (typeof val === 'string') out[k] = val
+  }
+  return out
+}
+
+export function writePersistedListQuery(
+  req: unknown,
+  key: string,
+  query: Record<string, unknown>,
+): void {
+  const session = getSession(req)
+  if (!session) return
+  const slice: Record<string, string> = {}
+  for (const [k, v] of Object.entries(query)) {
+    if (EXCLUDED_KEYS.has(k)) continue
+    if (isPageKey(k))         continue
+    if (typeof v !== 'string') continue
+    slice[k] = v
+  }
+  const prev = session.get<Record<string, unknown> | undefined>(key)
+  if (prev && shallowEqualStringMap(prev, slice)) return
+  session.put(key, slice)
+}
+
+export function readPersistedLastTab(
+  req: unknown,
+  basePath: string,
+  slug: string,
+): string | undefined {
+  const session = getSession(req)
+  if (!session) return undefined
+  const v = session.get<unknown>(lastTabKey(basePath, slug))
+  if (typeof v !== 'string') return undefined
+  return v
+}
+
+export function writePersistedLastTab(
+  req: unknown,
+  basePath: string,
+  slug: string,
+  tab: string,
+): void {
+  const session = getSession(req)
+  if (!session) return
+  const key = lastTabKey(basePath, slug)
+  if (session.get<string>(key) === tab) return
+  session.put(key, tab)
+}
+
+export function encodePersistedQuery(
+  slice: Record<string, string>,
+  tab:   string = '',
+): string {
+  const params = new URLSearchParams()
+  if (tab !== '') params.set('tab', tab)
+  for (const [k, v] of Object.entries(slice)) {
+    if (v === '') continue
+    params.set(k, v)
+  }
+  return params.toString()
+}
+
+function shallowEqualStringMap(
+  a: Record<string, unknown>,
+  b: Record<string, string>,
+): boolean {
+  const ak = Object.keys(a)
+  const bk = Object.keys(b)
+  if (ak.length !== bk.length) return false
+  for (const k of bk) {
+    if (a[k] !== b[k]) return false
+  }
+  return true
+}

package/src/summarizers/Summarizer.test.ts

@@ -0,0 +1,84 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Sum, Average, Count, Range } from './Summarizer.js'
+
+describe('Summarizers', () => {
+  describe('Sum', () => {
+    it('sums numeric values', () => {
+      assert.equal(Sum.make().compute([1, 2, 3, 4]), '10')
+    })
+
+    it('coerces strings and ignores non-numerics', () => {
+      assert.equal(Sum.make().compute(['10', '5', null, undefined, 'abc']), '15')
+    })
+
+    it('returns 0 over an empty list', () => {
+      assert.equal(Sum.make().compute([]), '0')
+    })
+
+    it('applies a custom format function', () => {
+      const formatted = Sum.make()
+        .format((n) => new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(n))
+        .compute([1.5, 2.25, 3])
+      assert.equal(formatted, '$6.75')
+    })
+  })
+
+  describe('Average', () => {
+    it('averages numeric values', () => {
+      assert.equal(Average.make().compute([2, 4, 6]), '4')
+    })
+
+    it('returns 0 for an empty list', () => {
+      assert.equal(Average.make().compute([]), '0')
+    })
+
+    it('skips non-numerics in the denominator', () => {
+      assert.equal(Average.make().compute([10, 'bad', 20]), '15')
+    })
+  })
+
+  describe('Count', () => {
+    it('counts every entry, including non-numerics', () => {
+      assert.equal(Count.make().compute([1, 'a', null, undefined]), '4')
+    })
+
+    it('returns 0 for empty input', () => {
+      assert.equal(Count.make().compute([]), '0')
+    })
+
+    it('ignores label and format options for the value (Count is integer-only)', () => {
+      const c = Count.make().label('Total entries').format(() => 'should be ignored')
+      assert.equal(c.compute([1, 2, 3]), '3')
+      assert.equal(c.toMeta().label, 'Total entries')
+    })
+  })
+
+  describe('Range', () => {
+    it('returns "min..max" over numeric values', () => {
+      assert.equal(Range.make().compute([3, 1, 4, 1, 5, 9, 2]), '1..9')
+    })
+
+    it('returns "—" when no numeric values are present', () => {
+      assert.equal(Range.make().compute([null, undefined, 'abc']), '—')
+    })
+
+    it('uses format function on each end of the range', () => {
+      const r = Range.make().format((n) => `$${n}`).compute([5, 25, 10])
+      assert.equal(r, '$5..$25')
+    })
+  })
+
+  describe('toResult / toMeta', () => {
+    it('toMeta carries kind + label only (no value)', () => {
+      const m = Sum.make().label('Total').toMeta()
+      assert.deepEqual(m, { kind: 'sum', label: 'Total' })
+    })
+
+    it('toResult bundles label + computed value', () => {
+      const r = Average.make().label('Avg').toResult([10, 20])
+      assert.deepEqual(r, { kind: 'average', label: 'Avg', value: '15' })
+    })
+  })
+})

package/src/summarizers/Summarizer.ts

@@ -0,0 +1,123 @@
+/**
+ * Column summarizers — small server-side aggregators over the rows the
+ * table just rendered. Attached via `Column.summarize([Sum.make(), …])`,
+ * computed inside `loadTableRecords`, and stamped onto `TableMeta.summaries`
+ * for the renderer to display in a `<tfoot>` row.
+ *
+ * v1 scope: per-page only (computes over the rows currently rendered),
+ * not across the full filtered set. Cross-page aggregation would need
+ * a separate query against the model and is deferred.
+ */
+
+export type SummarizerKind = 'sum' | 'average' | 'count' | 'range'
+
+export interface SummarizerMeta {
+  kind:   SummarizerKind
+  label?: string
+}
+
+export interface SummaryResult {
+  kind:   SummarizerKind
+  value:  string
+  label?: string
+}
+
+export type SummaryFormatter = (value: number) => string
+
+export abstract class Summarizer {
+  protected _label?:  string
+  protected _format?: SummaryFormatter
+
+  abstract readonly kind: SummarizerKind
+
+  /** Inline label rendered before the value (e.g. "Total: 42"). */
+  label(l: string): this { this._label = l; return this }
+
+  /** Custom number formatter — pair with `Intl.NumberFormat` for currency
+   * / locale-aware output. `Count` ignores formatters. */
+  format(fn: SummaryFormatter): this { this._format = fn; return this }
+
+  getLabel(): string | undefined { return this._label }
+  getFormatter(): SummaryFormatter | undefined { return this._format }
+
+  /** Compute the summary value from the rows' values for this column. */
+  abstract compute(values: ReadonlyArray<unknown>): string
+
+  toMeta(): SummarizerMeta {
+    return {
+      kind: this.kind,
+      ...(this._label !== undefined ? { label: this._label } : {}),
+    }
+  }
+
+  /** Run `compute` and bundle with the meta into a SummaryResult. */
+  toResult(values: ReadonlyArray<unknown>): SummaryResult {
+    return {
+      kind:  this.kind,
+      value: this.compute(values),
+      ...(this._label !== undefined ? { label: this._label } : {}),
+    }
+  }
+
+  /** Coerce a list of cell values into numbers, dropping non-numerics.
+   * `null` is excluded explicitly — `Number(null)` is 0, which would
+   * otherwise pollute averages and ranges. Empty strings, undefined,
+   * and unparseable strings are also dropped. */
+  protected toNumbers(values: ReadonlyArray<unknown>): number[] {
+    const out: number[] = []
+    for (const v of values) {
+      if (v === null || v === undefined || v === '') continue
+      const n = typeof v === 'number' ? v : Number(v)
+      if (!Number.isNaN(n) && Number.isFinite(n)) out.push(n)
+    }
+    return out
+  }
+
+  protected formatNumber(n: number): string {
+    return this._format ? this._format(n) : String(n)
+  }
+}
+
+export class Sum extends Summarizer {
+  readonly kind = 'sum' as const
+  static make(): Sum { return new Sum() }
+  override compute(values: ReadonlyArray<unknown>): string {
+    const total = this.toNumbers(values).reduce((a, b) => a + b, 0)
+    return this.formatNumber(total)
+  }
+}
+
+export class Average extends Summarizer {
+  readonly kind = 'average' as const
+  static make(): Average { return new Average() }
+  override compute(values: ReadonlyArray<unknown>): string {
+    const nums = this.toNumbers(values)
+    if (nums.length === 0) return this.formatNumber(0)
+    const avg = nums.reduce((a, b) => a + b, 0) / nums.length
+    return this.formatNumber(avg)
+  }
+}
+
+export class Count extends Summarizer {
+  readonly kind = 'count' as const
+  static make(): Count { return new Count() }
+  override compute(values: ReadonlyArray<unknown>): string {
+    return String(values.length)
+  }
+}
+
+export class Range extends Summarizer {
+  readonly kind = 'range' as const
+  static make(): Range { return new Range() }
+  override compute(values: ReadonlyArray<unknown>): string {
+    const nums = this.toNumbers(values)
+    if (nums.length === 0) return '—'
+    let min = nums[0]!
+    let max = nums[0]!
+    for (const n of nums) {
+      if (n < min) min = n
+      if (n > max) max = n
+    }
+    return `${this.formatNumber(min)}..${this.formatNumber(max)}`
+  }
+}