@gscdump/nuxt 0.21.3 → 0.22.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/nuxt",
   "type": "module",
-  "version": "0.21.3",
+  "version": "0.22.1",
   "description": "Nuxt layer: GSC analytics UI + DuckDB-WASM integration. Frontend-only; server primitives live in @gscdump/analysis, @gscdump/engine-sqlite, @gscdump/cloudflare, and host apps.",
   "author": {
     "name": "Harlan Wilton",
@@ -47,20 +47,21 @@
   },
   "dependencies": {
     "@duckdb/duckdb-wasm": "^1.32.0",
-    "@nuxt/ui": "^4.7.1",
+    "@nuxt/ui": "^4.8.0",
     "@unovis/ts": "^1.6.5",
     "@unovis/vue": "^1.6.5",
     "@vueuse/core": "^14.3.0",
     "@vueuse/nuxt": "^14.3.0",
     "defu": "^6.1.7",
+    "nuxt-use-query": "^0.1.0",
     "ofetch": "^1.5.1",
     "tailwindcss": "^4.3.0",
-    "@gscdump/analysis": "0.21.3",
-    "@gscdump/contracts": "0.21.3",
-    "@gscdump/engine": "0.21.3",
-    "@gscdump/engine-duckdb-wasm": "0.21.3",
-    "gscdump": "0.21.3",
-    "@gscdump/sdk": "0.21.3"
+    "@gscdump/analysis": "0.22.1",
+    "@gscdump/contracts": "0.22.1",
+    "@gscdump/engine": "0.22.1",
+    "@gscdump/engine-duckdb-wasm": "0.22.1",
+    "@gscdump/sdk": "0.22.1",
+    "gscdump": "0.22.1"
   },
   "devDependencies": {
     "@nuxt/kit": "^4.4.6",

package/types.ts

@@ -46,6 +46,7 @@ declare module '#app' {
   }
 }
 
+export type { GscAnalyzerInstance, GscAnalyzerTimings } from './app/composables/useGscAnalyzer'
 export type {
   GscAnalyzerBatchEntry,
   GscAnalyzerBatchRunner,
@@ -65,15 +66,14 @@ export type {
   GscAnalyzerPanelSpec,
   GscAnalyzerStatTile,
 } from './app/composables/useGscAnalyzerDefs'
-
 export { gscPanelRunnerKey, useGscPanelRunner } from './app/composables/useGscPanelContext'
 
 export type { GscPanelRunnerContext } from './app/composables/useGscPanelContext'
+
 export type {
   UseGscParquetTableOptions,
   UseGscParquetTableReturn,
 } from './app/composables/useGscParquetTable'
-
 export type {
   GscBackfillRunner,
   GscQueryDecision,
@@ -85,7 +85,12 @@ export type {
   UseGscQueryReturn,
 } from './app/composables/useGscQuery'
 
-export type { UseGscRollupTableOptions } from './app/composables/useGscRollupTable'
+export type {
+  GscFactTable,
+  GscTableStage,
+  GscTableStatus,
+  UseGscSiteAnalyzerReturn,
+} from './app/composables/useGscSiteAnalyzer'
 
 export type {
   AnalysisSourcesResponse,

package/app/composables/useGscEngine.ts

@@ -1,16 +0,0 @@
-// App-wide engine override for `useGscQuery`. SSR-safe via `useState`.
-//
-// Resolution priority lives in `useGscQueryDispatcher.pickEngine`:
-//   per-call `opts.engine` → `useGscEngine().value` → `runtimeConfig.public.
-//   analytics.defaultEngine` → `'auto'`.
-//
-// Set the value once on the consumer side (e.g. from your auth plugin's
-// `onReady` hook reading a per-user feature flag) and every query inherits.
-
-import type { GscQueryEngine } from './useGscQuery'
-
-const STATE_KEY = 'gscdump:engine'
-
-export function useGscEngine(): Ref<GscQueryEngine | null> {
-  return useState<GscQueryEngine | null>(STATE_KEY, () => null)
-}

package/app/composables/useGscRollupTable.ts

@@ -1,78 +0,0 @@
-// Top-N rollup table state for list pages.
-//
-// Owns the canonical wiring previously duplicated across consumer apps:
-//   - shared `useGscPeriod` + windowed range
-//   - `useGscRollup` fetch
-//   - URL-synced search/sort via `useGscTableState`
-//   - debounced fuzzy filter on one row field
-//   - position-aware sort (sort key 'position' invokes `positionFor`)
-//   - top-N slice (default 100)
-//
-// Row shape contract: `impressions` + `sum_position` so `positionFor` works
-// without a caller-supplied accessor.
-
-import type { MaybeRefOrGetter, Ref } from '@vue/runtime-core'
-
-interface SortState { column: string, direction: 'asc' | 'desc' }
-
-export interface UseGscRollupTableOptions<TRow> {
-  siteId: MaybeRefOrGetter<string>
-  rollupKey: string
-  filterField: keyof TRow & string
-  defaultSort?: SortState
-  limit?: number
-  debounceMs?: number
-}
-
-// eslint-disable-next-line ts/explicit-function-return-type -- complex generic inference; explicit type would diverge as composables evolve
-export function useGscRollupTable<
-  TRow extends { impressions: number, sum_position: number },
->(opts: UseGscRollupTableOptions<TRow>) {
-  const { period, compareMode, stableData, range } = useGscPeriod()
-  const windowRange = computed(() => ({ start: range.value.start, end: range.value.end }))
-
-  const { data: payload, loading } = useGscRollup<TRow[]>(
-    opts.siteId,
-    opts.rollupKey,
-    { range: windowRange },
-  )
-
-  const { q, sort, toggleSort } = useGscTableState({ defaultSort: opts.defaultSort })
-
-  const searchDebounced = refDebounced<string>(q, opts.debounceMs ?? 150)
-
-  const limit = opts.limit ?? 100
-  const rows = computed<TRow[]>(() => {
-    const needle = searchDebounced.value.trim().toLowerCase()
-    const source = (payload.value ?? []).slice()
-    const filtered = needle
-      ? source.filter((r: TRow) => {
-          const v = (r as Record<string, unknown>)[opts.filterField]
-          return typeof v === 'string' && v.toLowerCase().includes(needle)
-        })
-      : source
-    const s = sort.value
-    if (s) {
-      const dir = s.direction === 'desc' ? -1 : 1
-      filtered.sort((a: TRow, b: TRow) => {
-        const av = s.column === 'position' ? positionFor(a) : ((a as Record<string, unknown>)[s.column] as number)
-        const bv = s.column === 'position' ? positionFor(b) : ((b as Record<string, unknown>)[s.column] as number)
-        return av < bv ? -1 * dir : av > bv ? 1 * dir : 0
-      })
-    }
-    return filtered.slice(0, limit)
-  })
-
-  return {
-    period,
-    compareMode,
-    stableData,
-    range,
-    q,
-    sort,
-    toggleSort,
-    payload: payload as Ref<TRow[] | null>,
-    loading,
-    rows,
-  }
-}

package/app/composables/useGscRowQuery.ts

@@ -1,56 +0,0 @@
-// Thin client wrapper over POST /api/__gsc/sites/[siteId]/rows. Takes a
-// BuilderState (or a typed query builder) and returns reactive rows with
-// auto-refetch when the state / site changes.
-//
-// Use for row-level page needs (country breakdowns, top-N with custom
-// filters, per-page drilldowns, …). For analyzer-style transforms, use
-// `useGscQuery` which dispatches via /analyze.
-
-import type { QueryRow } from '@gscdump/analysis'
-import type { GscRowQueryMeta, GscRowQueryResponse } from '@gscdump/contracts'
-import type { ComputedRef, Ref } from '@vue/runtime-core'
-import type { BuilderState } from 'gscdump/query'
-import { useGscResource } from './_useGscResource'
-import { useGscAnalyticsClient } from './useGscAnalyticsClient'
-
-export type { GscRowQueryMeta, GscRowQueryResponse } from '@gscdump/contracts'
-
-export interface UseGscRowQueryOptions {
-  site: MaybeRefOrGetter<string | null | undefined>
-  state: MaybeRefOrGetter<BuilderState | null | undefined>
-  /** Gate the query; when `false` stays idle (useful for lazy tabs). */
-  enabled?: MaybeRefOrGetter<boolean>
-}
-
-export interface UseGscRowQueryReturn<T> {
-  rows: ComputedRef<T[]>
-  meta: ComputedRef<GscRowQueryMeta | null>
-  loading: Ref<boolean>
-  error: Ref<Error | null>
-  refresh: () => Promise<void>
-}
-
-export function useGscRowQuery<T = QueryRow>(
-  opts: UseGscRowQueryOptions,
-): UseGscRowQueryReturn<T> {
-  const resource = useGscResource<[string, BuilderState], GscRowQueryResponse<T>>({
-    keys: [
-      () => (opts.enabled === undefined || toValue(opts.enabled) ? toValue(opts.site) : null),
-      // BuilderState is structural; stringify so keys[]-watch picks up shape changes.
-      () => {
-        const s = toValue(opts.state)
-        return s ? JSON.stringify(s) as unknown as BuilderState : null
-      },
-    ],
-    fetcher: site => useGscAnalyticsClient().queryRows<T>(site, toValue(opts.state) as BuilderState),
-    isEmpty: r => r.rows.length === 0,
-  })
-
-  return {
-    rows: computed(() => resource.data.value?.rows ?? []),
-    meta: computed(() => resource.data.value?.meta ?? null),
-    loading: resource.loading as unknown as Ref<boolean>,
-    error: resource.error,
-    refresh: resource.refresh,
-  }
-}

package/app/composables/useGscSnapshotAnalyzer.contract.ts

@@ -1,150 +0,0 @@
-/**
- * CONTRACT — consolidated analyzer composable public API (Wave-2, frozen).
- *
- * The single composable that replaces BOTH `useGscAnalyzer.ts` (pkg) and
- * `useBrowserAnalyzer.ts` (app). One OPFS-backed, attach-once, browser-
- * eligibility-aware analyzer.
- *
- * This file is the INTERFACE ONLY — the Wave-2 implementation agent writes
- * `useGscSnapshotAnalyzer.ts` against these types, then deletes the two old
- * composables. Naming follows the package convention (`useGsc*`).
- *
- * Behaviour the types lock in:
- * - ATTACH-ONCE — DuckDB-WASM boots once; OPFS-cached parquet attaches once
- *   per `(site, searchType)`. Filter / date-range changes within the attached
- *   span re-query, they do NOT re-attach.
- * - OPFS-backed — files resolved via the file-resolution endpoint are cached
- *   in OPFS (content-hash verified); steady-state queries are zero-network.
- * - RESULT LRU — identical archetype queries replay from an in-memory LRU.
- * - BROWSER-ELIGIBILITY AWARE — when the file-resolution endpoint returns a
- *   server-tail directive for a table, `query()` for that table transparently
- *   routes server-side; the consumer does not branch.
- *
- * TYPES ONLY — no composable body.
- */
-
-import type { GscSearchType } from '@gscdump/contracts'
-import type {
-  ArchetypeQuery,
-  ArchetypeResult,
-  ArchetypeResultRow,
-} from '@gscdump/sdk'
-import type { MaybeRefOrGetter, Ref } from 'vue'
-
-/** Date window the analyzer is attached over. */
-export interface AnalyzerRange {
-  start: string
-  end: string
-}
-
-/** Boot / attach lifecycle phase, surfaced for the progress UI. */
-export type AnalyzerPhase
-  = | 'idle'
-    | 'resolving' // calling the file-resolution endpoint
-    | 'booting' // DuckDB-WASM boot
-    | 'downloading' // fetching parquet into OPFS
-    | 'attaching' // registering OPFS files as DuckDB views
-    | 'ready'
-    | 'error'
-
-/** Progressive-load progress, drives `<GscBootProgress>`. */
-export interface AnalyzerProgress {
-  phase: AnalyzerPhase
-  /** Files fetched into OPFS so far. */
-  filesReady: number
-  /** Total files to fetch for the current attach. */
-  filesTotal: number
-  /** Bytes fetched into OPFS so far. */
-  bytesReady: number
-  bytesTotal: number
-  startedAt?: number
-  endedAt?: number
-  error?: string
-}
-
-/** OPFS storage health, surfaced so the UI can warn before eviction. */
-export interface AnalyzerStorageState {
-  /** `navigator.storage.persist()` result. `false` => eviction-eligible. */
-  persisted: boolean
-  /** Estimated bytes used by this origin's OPFS. */
-  usageBytes?: number
-  /** Estimated quota. */
-  quotaBytes?: number
-  /** True after a `QuotaExceededError` forced a degraded (server-tail) path. */
-  degraded: boolean
-}
-
-/**
- * Per-table routing the analyzer resolved. `'browser'` tables answer locally
- * from OPFS; `'server'` tables route to the server tail. Consumers may read
- * this to show "deep history served from the cloud" UX.
- */
-export type AnalyzerTableRouting = Record<string, 'browser' | 'server'>
-
-/** Options for `useGscSnapshotAnalyzer`. */
-export interface GscSnapshotAnalyzerOptions {
-  /** Max entries in the result LRU. Default implementation-defined. */
-  resultCacheSize?: number
-}
-
-/**
- * The consolidated analyzer instance. Refs are reactive over the currently
- * bound `(site, searchType, range)` — switching any of them rebinds and the
- * refs track the new attach with no manual mirroring.
- */
-export interface GscSnapshotAnalyzer {
-  /** True once the analyzer can serve `query()` (browser attached OR server-tail ready). */
-  ready: Ref<boolean>
-  /** True while resolving / booting / attaching. */
-  initializing: Ref<boolean>
-  error: Ref<Error | null>
-  progress: Ref<AnalyzerProgress>
-  storage: Ref<AnalyzerStorageState>
-  /** Per-table browser vs server routing for the current attach. */
-  routing: Ref<AnalyzerTableRouting>
-  /** Snapshot version of the currently-attached file set (re-attach trigger). */
-  snapshotVersion: Ref<string | undefined>
-  /** The site currently bound. */
-  currentSiteId: Ref<string | null>
-
-  /**
-   * Run a typed archetype query. Routes automatically:
-   * - browser-eligible tables → DuckDB-WASM over OPFS files.
-   * - server-tail tables      → R2 SQL or server DuckDB per the directive.
-   * Identical queries replay from the result LRU. Honours `signal`.
-   */
-  query: <R extends ArchetypeResultRow = ArchetypeResultRow>(
-    q: ArchetypeQuery,
-    opts?: { signal?: AbortSignal },
-  ) => Promise<ArchetypeResult<R>>
-
-  /**
-   * Re-probe the file-resolution endpoint; if `snapshotVersion` changed,
-   * detach stale views and re-attach the fresher parquet in place (the
-   * DuckDB-WASM runtime stays alive). Resolves true if it re-attached.
-   * No-op for fully server-tail-routed sites.
-   */
-  refresh: () => Promise<boolean>
-
-  /** Drop the result LRU without detaching. Cheap cache bust. */
-  clearCache: () => void
-
-  /** Detach views, close the runtime, release OPFS handles. Idempotent. */
-  dispose: () => Promise<void>
-}
-
-/**
- * Get (or create) the consolidated analyzer for a site. Per-`(site,
- * searchType, range)` cached + refcounted across the app, so panels on the
- * same site share one DuckDB-WASM boot and one OPFS attach.
- *
- * Replaces `useGscAnalyzer` (pkg) and `useBrowserAnalyzer` /
- * `provideBrowserAnalyzer` / `useSharedBrowserAnalyzer` (app) — those are
- * deleted once consumers migrate.
- */
-export type UseGscSnapshotAnalyzer = (
-  siteId: MaybeRefOrGetter<string | null | undefined>,
-  searchType?: MaybeRefOrGetter<GscSearchType | undefined>,
-  range?: MaybeRefOrGetter<AnalyzerRange | null | undefined>,
-  options?: GscSnapshotAnalyzerOptions,
-) => GscSnapshotAnalyzer

package/app/composables/useGscSnapshotAnalyzer.routing.ts

@@ -1,87 +0,0 @@
-/**
- * Pure routing + caching helpers for `useGscSnapshotAnalyzer`.
- *
- * Extracted into a standalone, Nuxt-free module so the routing decision and
- * the result LRU are unit-testable without a Nuxt runtime (the composable file
- * itself depends on Nuxt auto-imports).
- */
-
-import type { ArchetypeQuery } from '@gscdump/sdk'
-import type { AnalyzerTableRouting } from './useGscSnapshotAnalyzer.contract'
-
-/**
- * Decide where an archetype query runs given the analyzer's per-table routing.
- *
- * - `aux-cloud-only` is always `cloud` (not an Iceberg query).
- * - Otherwise the fact-table the archetype reads decides: a table the resolver
- *   marked `browser` runs locally; `server` (or degraded by a quota error)
- *   routes to the server tail. An unknown table fails safe to `server`.
- */
-export function routeArchetype(
-  query: ArchetypeQuery,
-  routing: AnalyzerTableRouting,
-  tableOf: (q: ArchetypeQuery) => string | null,
-): 'browser' | 'server' | 'cloud' {
-  if (query.archetype === 'aux-cloud-only')
-    return 'cloud'
-  const table = tableOf(query)
-  if (!table)
-    return 'cloud'
-  return routing[table] === 'browser' ? 'browser' : 'server'
-}
-
-/**
- * Stable hash of an archetype query for the result LRU. Archetype inputs are
- * flat + declarative; keys are sorted so insertion order can't perturb the key.
- */
-export function archetypeQueryHash(query: ArchetypeQuery): string {
-  return JSON.stringify(query, Object.keys(query as unknown as Record<string, unknown>).sort())
-}
-
-/**
- * Compose the LRU cache key. Keyed by `snapshotVersion` so a fresh compaction
- * (new snapshot) invalidates every cached result without an explicit bust.
- */
-export function resultCacheKey(snapshotVersion: string | undefined, query: ArchetypeQuery): string {
-  return `${snapshotVersion ?? 'none'}::${archetypeQueryHash(query)}`
-}
-
-export interface ResultLru<V> {
-  get: (key: string) => V | undefined
-  set: (key: string, value: V) => void
-  clear: () => void
-  readonly size: number
-}
-
-/** Minimal insertion-ordered LRU. Re-inserts on `get` to mark recency. */
-export function createResultLru<V>(capacity: number): ResultLru<V> {
-  const map = new Map<string, V>()
-  const cap = Math.max(1, Math.floor(capacity))
-  return {
-    get(key) {
-      if (!map.has(key))
-        return undefined
-      const value = map.get(key)!
-      map.delete(key)
-      map.set(key, value)
-      return value
-    },
-    set(key, value) {
-      if (map.has(key))
-        map.delete(key)
-      map.set(key, value)
-      while (map.size > cap) {
-        const oldest = map.keys().next().value
-        if (oldest === undefined)
-          break
-        map.delete(oldest)
-      }
-    },
-    clear() {
-      map.clear()
-    },
-    get size() {
-      return map.size
-    },
-  }
-}