@gscdump/nuxt 0.22.4 → 1.5.1

package/app/composables/_useGscResource.ts

@@ -1,202 +0,0 @@
-// Site-keyed async resource composable. Owns key-watch, status classification,
-// refresh, and cache policy for every read-only `/api/__gsc/*` operation in
-// the layer. Resource composables stay thin adapters that wire reactive keys
-// to `gscQueries.*(...)` operations (preferred) — or to a `fetcher` for the
-// rollup composables that mix multiple operations + progress side-effects.
-
-import type { ComputedRef, Ref, WatchSource } from '@vue/runtime-core'
-import type { NuxtRpcQueryOperation } from 'nuxt-use-query/rpc'
-import type { GscErrorStatus } from '../utils/gsc-error'
-import { useNuxtRpcQuery } from 'nuxt-use-query/rpc'
-import { classifyGscError } from '../utils/gsc-error'
-import { useGscFetch } from '../utils/gsc-fetch'
-
-export type GscResourceStatus = 'idle' | 'pending' | 'success' | 'empty' | GscErrorStatus
-
-export interface UseGscResourceOptions<TArgs extends readonly unknown[], TData> {
-  /** Reactive args passed to the fetcher. Resource stays idle while any required key is null/undefined. */
-  keys: { [I in keyof TArgs]: MaybeRefOrGetter<TArgs[I] | null | undefined> }
-  /** RPC query operation invoked with the resolved keys. Preferred over `fetcher` — gets Zod validation + shared cache keying. */
-  operation?: (...args: TArgs) => NuxtRpcQueryOperation<any, any>
-  /** Composite async fetcher invoked with the resolved keys. Use only when an operation can't model the request (multi-call, progress side-effects). */
-  fetcher?: (...args: TArgs) => Promise<TData | null>
-  /** Predicate for the `empty` status — defaults to checking `null`/`[]`/typical container fields. */
-  isEmpty?: (data: TData) => boolean
-  /** Extra reactive sources that should retrigger a fetch. */
-  watchSources?: WatchSource[]
-  /** Optional namespace for the fetcher-mode cache key. Defaults to `gsc-resource`. Ignored when `operation` is provided (the operation owns its key). */
-  namespace?: string
-  /** Milliseconds before cached data is considered stale. Defaults to `nuxt-use-query`'s 0. */
-  staleTime?: number
-  /** Evict cached payload after the last consumer unmounts. Defaults to `nuxt-use-query`'s 5 min. */
-  gcTime?: number
-}
-
-export interface UseGscResourceReturn<TData> {
-  data: Readonly<Ref<TData | null>>
-  status: Readonly<Ref<GscResourceStatus>>
-  loading: ComputedRef<boolean>
-  error: Readonly<Ref<Error | null>>
-  refresh: () => Promise<void>
-}
-
-function defaultIsEmpty(v: unknown): boolean {
-  if (v == null)
-    return true
-  if (Array.isArray(v))
-    return v.length === 0
-  if (typeof v === 'object') {
-    const rec = v as Record<string, unknown>
-    for (const key of ['rows', 'records', 'snapshots', 'items', 'results']) {
-      const arr = rec[key]
-      if (Array.isArray(arr))
-        return arr.length === 0
-    }
-  }
-  return false
-}
-
-export function useGscResource<TArgs extends readonly unknown[], TData>(
-  opts: UseGscResourceOptions<TArgs, TData>,
-): UseGscResourceReturn<TData> {
-  const namespace = opts.namespace ?? 'gsc-resource'
-  const resolvedArgs = computed<TArgs | null>(() => {
-    const out: unknown[] = []
-    for (const k of opts.keys) {
-      const v = toValue(k)
-      if (v == null || v === '')
-        return null
-      out.push(v)
-    }
-    return out as unknown as TArgs
-  })
-
-  const enabled = computed(() => resolvedArgs.value != null)
-  const gscFetch = useGscFetch()
-
-  // Operation branch: route through useNuxtRpcQuery so we inherit Zod
-  // response validation, RPC key serialization, and shared cache invalidation.
-  if (opts.operation) {
-    const operation = computed<NuxtRpcQueryOperation<any, any> | null>(() => {
-      const args = resolvedArgs.value
-      return args ? opts.operation!(...args) : null
-    })
-
-    // Idle placeholder when args aren't ready — useNuxtRpcQuery is always
-    // mounted, but the `enabled` gate prevents the request firing.
-    const fallbackOp = { key: `${namespace}:idle`, path: `${namespace}:idle`, response: { parse: (v: unknown) => v } as any }
-
-    const query = useNuxtRpcQuery<any>(
-      () => operation.value ?? fallbackOp,
-      {
-        enabled,
-        watch: opts.watchSources,
-        staleTime: opts.staleTime,
-        gcTime: opts.gcTime,
-        $fetch: gscFetch as any,
-      } as any,
-    )
-
-    const data = computed<TData | null>(() => {
-      if (!enabled.value)
-        return null
-      return (query.displayData.value ?? null) as TData | null
-    })
-
-    const error = computed<Error | null>(() => {
-      if (!enabled.value)
-        return null
-      const e = query.error.value
-      return e == null ? null : e instanceof Error ? e : new Error(String(e))
-    })
-
-    const status = computed<GscResourceStatus>(() => {
-      if (!enabled.value)
-        return 'idle'
-      if (query.status.value === 'pending')
-        return 'pending'
-      if (query.status.value === 'error') {
-        const classified = classifyGscError(error.value)
-        return classified.status
-      }
-      const out = data.value
-      if (query.status.value === 'success')
-        return out == null || (opts.isEmpty ?? defaultIsEmpty)(out) ? 'empty' : 'success'
-      return 'idle'
-    })
-
-    const loading = computed(() => status.value === 'pending')
-
-    async function refresh(): Promise<void> {
-      if (!enabled.value)
-        return
-      await query.refresh()
-    }
-
-    return { data, status, loading, error, refresh }
-  }
-
-  // Fetcher branch: composables that can't be modelled as a single RPC
-  // operation (rollup fan-out, progress tracking) drop down to a raw
-  // useNuxtQuery + bound $fetch.
-  const queryKey = computed(() => {
-    const args = resolvedArgs.value
-    return args ? `${namespace}:${JSON.stringify(args)}` : `${namespace}:idle`
-  })
-
-  const fetchResource = (async () => {
-    const args = resolvedArgs.value
-    if (!args)
-      return null
-    if (opts.fetcher)
-      return await opts.fetcher(...args)
-    throw new Error('useGscResource: no operation or fetcher configured')
-  }) as unknown as typeof $fetch
-
-  const query = useNuxtQuery<TData | null, Error>(() => queryKey.value, {
-    key: () => queryKey.value,
-    enabled,
-    watch: opts.watchSources,
-    staleTime: opts.staleTime,
-    gcTime: opts.gcTime,
-    $fetch: fetchResource,
-  })
-
-  const data = computed<TData | null>(() => {
-    if (!enabled.value)
-      return null
-    return (query.displayData.value ?? null) as TData | null
-  })
-
-  const error = computed<Error | null>(() => {
-    if (!enabled.value)
-      return null
-    const e = query.error.value
-    return e == null ? null : e instanceof Error ? e : new Error(String(e))
-  })
-
-  const status = computed<GscResourceStatus>(() => {
-    if (!enabled.value)
-      return 'idle'
-    if (query.status.value === 'pending')
-      return 'pending'
-    if (query.status.value === 'error') {
-      const classified = classifyGscError(error.value)
-      return classified.status
-    }
-    const out = data.value
-    if (query.status.value === 'success')
-      return out == null || (opts.isEmpty ?? defaultIsEmpty)(out) ? 'empty' : 'success'
-    return 'idle'
-  })
-
-  const loading = computed(() => status.value === 'pending')
-
-  async function refresh(): Promise<void> {
-    if (!enabled.value)
-      return
-    await query.refresh()
-  }
-
-  return { data, status, loading, error, refresh }
-}

package/app/composables/_useGscSharedSiteResource.ts

@@ -1,136 +0,0 @@
-// Per-site shared resource bag. Consolidates the bind/unbind/refcount pattern
-// that useGscAnalyzer and useGscAnalyticsSourceInfo each reinvented.
-//
-// Two entry points share one underlying bag (a module-scope WeakMap keyed by
-// the NuxtApp instance, so each app gets isolated state and SSR is safe):
-//   - useGscSharedSiteResource → composable, refcounted, scope-disposed.
-//   - acquireSharedEntry       → non-composable acquire for boot-time / non-
-//                                setup callers (e.g. analyzer createInstance).
-//
-// Refcounting via `onDispose` is opt-in:
-//   - omitted     → entry persists forever (cheap, share-only; e.g. /source-info)
-//   - provided    → refcounted; runs onDispose + drops the entry at refs=0
-//
-// Returns a `bound` computed that tracks the entry for the current siteId. The
-// caller wraps it in `computed(() => bound.value?.field ?? default)` to expose
-// reactive fields.
-
-import type { ComputedRef } from '@vue/runtime-core'
-import type { NuxtApp } from 'nuxt/app'
-
-interface CacheEntry<T> {
-  entry: T
-  refs: number
-}
-
-type NamespaceBag = Map<string, Map<string, CacheEntry<unknown>>>
-
-const bags = new WeakMap<NuxtApp, NamespaceBag>()
-
-function namespaceMap(namespace: string): Map<string, CacheEntry<unknown>> {
-  const app = useNuxtApp()
-  let bag = bags.get(app)
-  if (!bag) {
-    bag = new Map()
-    bags.set(app, bag)
-  }
-  let m = bag.get(namespace)
-  if (!m) {
-    m = new Map()
-    bag.set(namespace, m)
-  }
-  return m
-}
-
-/**
- * Non-composable acquire — returns (and lazily creates) the shared entry for
- * `(namespace, siteId)`. No refcount, no scope dispose. Intended for callers
- * outside a Vue setup scope (analyzer boot IIFE, one-shot loaders) that still
- * need to share state with the reactive `useGscSharedSiteResource` consumers.
- */
-export function acquireSharedEntry<T>(
-  namespace: string,
-  siteId: string,
-  factory: (siteId: string) => T,
-): T {
-  const cache = namespaceMap(namespace) as Map<string, CacheEntry<T>>
-  let inst = cache.get(siteId)
-  if (!inst) {
-    inst = { entry: factory(siteId), refs: 0 }
-    cache.set(siteId, inst)
-  }
-  return inst.entry
-}
-
-export interface UseSharedSiteResourceOptions<T> {
-  /** Build the entry on first acquire for a site. */
-  factory: (siteId: string) => T
-  /** When set, refcount the entry and run on the last release (deletes from cache). */
-  onDispose?: (entry: T) => Promise<void> | void
-}
-
-export interface UseSharedSiteResourceReturn<T> {
-  bound: ComputedRef<T | null>
-  currentSiteId: Ref<string | null>
-}
-
-export function useGscSharedSiteResource<T>(
-  namespace: string,
-  siteId: MaybeRefOrGetter<string | null | undefined>,
-  opts: UseSharedSiteResourceOptions<T>,
-): UseSharedSiteResourceReturn<T> {
-  const cache = namespaceMap(namespace) as Map<string, CacheEntry<T>>
-
-  const boundRef = shallowRef<T | null>(null)
-  const currentSiteId = ref<string | null>(null)
-
-  function bind(id: string): void {
-    unbind()
-    let inst = cache.get(id)
-    if (!inst) {
-      inst = { entry: opts.factory(id), refs: 0 }
-      cache.set(id, inst)
-    }
-    inst.refs++
-    boundRef.value = inst.entry
-    currentSiteId.value = id
-  }
-
-  function unbind(): void {
-    const id = currentSiteId.value
-    if (!id) {
-      boundRef.value = null
-      return
-    }
-    const inst = cache.get(id)
-    boundRef.value = null
-    currentSiteId.value = null
-    if (!inst)
-      return
-    inst.refs--
-    if (inst.refs <= 0 && opts.onDispose) {
-      cache.delete(id)
-      void Promise.resolve(opts.onDispose(inst.entry)).catch(() => {})
-    }
-  }
-
-  watch(
-    () => toValue(siteId),
-    (id: string | null | undefined) => {
-      if (!id) {
-        unbind()
-        return
-      }
-      if (import.meta.client)
-        bind(id)
-    },
-    { immediate: true },
-  )
-
-  onScopeDispose(unbind)
-
-  return {
-    bound: computed(() => boundRef.value) as ComputedRef<T | null>,
-    currentSiteId,
-  }
-}

package/app/composables/useGscAnalytics.ts

@@ -1,206 +0,0 @@
-// Analytics context: sites list + shared boot-progress map + per-site analyzer
-// cache. Provided app-wide by the layer's plugin as `nuxtApp.$gscAnalytics`.
-// Pages reach in via narrower hooks (`useGscSites`, `useGscSite`,
-// `useGscAnalyzer`, `useGscBootProgress`) — no global mutable `currentSite`,
-// no leaked progress writers.
-
-import type { SiteListItem } from '@gscdump/contracts'
-import { useGscAnalyticsClient } from './useGscAnalyticsClient'
-
-export type { SiteListItem }
-
-export type ReadBackend = 'd1' | 'r2'
-
-export interface SiteRecord extends SiteListItem {
-  /** Canonical GSC site URL. Alias of `label` for back-compat. */
-  siteUrl: string
-  /**
-   * Which backend serves analysis for this site. Carried through from the
-   * sites endpoint; when omitted the value defaults to `'r2'` so legacy
-   * consumers keep working. Browser-attach eligibility is ultimately
-   * decided by the server's source provider via `browserAttachEligible`
-   * on `/api/__gsc/sites/:siteId/source-info`, not by this field.
-   */
-  readBackend: ReadBackend
-  syncStatus?: string | null
-}
-
-export type SiteLoadStage = 'idle' | 'wasm' | 'manifest' | 'attach' | 'ready' | 'error'
-
-export interface SiteLoadProgress {
-  siteId: string
-  stage: SiteLoadStage
-  /** Sub-units (parquet files, rollup JSONs) completed. */
-  filesAttached: number
-  /** Sub-units expected; 0 while unknown. */
-  filesTotal: number
-  startedAt: number
-  endedAt?: number
-  error?: string
-  source?: 'duckdb' | 'rollup' | string
-}
-
-export interface GscAnalyticsContext {
-  sites: Ref<SiteListItem[] | null>
-  sitesLoading: Readonly<Ref<boolean>>
-  sitesError: Readonly<Ref<Error | null>>
-  refreshSites: () => Promise<void>
-  progress: Readonly<Ref<Record<string, SiteLoadProgress>>>
-  /** Escape hatch for demos/tests — write raw progress entries. */
-  patchProgress: (siteId: string, patch: Partial<SiteLoadProgress>) => void
-  /** Escape hatch for demos/tests — clear progress map (all or one site). */
-  clearProgress: (siteId?: string) => void
-}
-
-// Factory exposed so the layer's Nuxt plugin can provide a single app-wide
-// context via `provide: { gscAnalytics: createGscAnalyticsContext() }`.
-export function createGscAnalyticsContext(): GscAnalyticsContext {
-  return createContext()
-}
-
-/** Resolve the shared context. The layer's plugin guarantees this is provided. */
-export function useGscAnalyticsContext(): GscAnalyticsContext {
-  return useNuxtApp().$gscAnalytics
-}
-
-/** Read-only sites list + refresh. */
-export function useGscSites(): {
-  sites: Ref<SiteListItem[] | null>
-  loading: Readonly<Ref<boolean>>
-  error: Readonly<Ref<Error | null>>
-  refresh: () => Promise<void>
-} {
-  const { sites, sitesLoading, sitesError, refreshSites } = useGscAnalyticsContext()
-  return { sites, loading: sitesLoading, error: sitesError, refresh: refreshSites }
-}
-
-/** Derived site record for a given id. Non-mutating; returns `null` until the list resolves. */
-export function useGscSite(siteId: MaybeRefOrGetter<string | null | undefined>): Ref<SiteRecord | null> {
-  const { sites } = useGscAnalyticsContext()
-  return computed(() => {
-    const id = toValue(siteId)
-    if (!id)
-      return null
-    const found = sites.value?.find((s: SiteListItem) => s.id === id)
-    if (found)
-      return toSiteRecord(found)
-    // List not yet loaded — stamp a minimal record so downstream queries can
-    // dispatch against the id. Gets upgraded when sites resolves.
-    return {
-      id,
-      label: id,
-      hostname: id,
-      propertyType: 'url-prefix',
-      siteUrl: id,
-      readBackend: 'r2',
-    }
-  })
-}
-
-function toSiteRecord(s: SiteListItem): SiteRecord {
-  return {
-    ...s,
-    siteUrl: s.label,
-    readBackend: s.readBackend ?? 'r2',
-  }
-}
-
-/** Read-only boot-progress map for UI indicators. */
-export function useGscBootProgress(): {
-  progress: Readonly<Ref<Record<string, SiteLoadProgress>>>
-  entries: ComputedRef<SiteLoadProgress[]>
-  allReady: ComputedRef<boolean>
-  anyActive: ComputedRef<boolean>
-} {
-  const { progress } = useGscAnalyticsContext()
-  const entries = computed<SiteLoadProgress[]>(() => {
-    const all = Object.values(progress.value) as SiteLoadProgress[]
-    return all.sort((a, b) => a.startedAt - b.startedAt)
-  })
-  const allReady = computed(() =>
-    entries.value.length > 0 && entries.value.every((s: SiteLoadProgress) => s.stage === 'ready'),
-  )
-  const anyActive = computed(() =>
-    entries.value.some((s: SiteLoadProgress) => s.stage !== 'ready' && s.stage !== 'idle' && s.stage !== 'error'),
-  )
-  return { progress, entries, allReady, anyActive }
-}
-
-function createContext(): GscAnalyticsContext {
-  const client = useGscAnalyticsClient()
-  const sites = ref<SiteListItem[] | null>(null)
-  const sitesLoading = ref(false)
-  const sitesError = ref<Error | null>(null)
-  const progress = ref<Record<string, SiteLoadProgress>>({})
-
-  async function refreshSites(): Promise<void> {
-    sitesLoading.value = true
-    sitesError.value = null
-    sites.value = await client.listSites().catch((err: unknown) => {
-      sitesError.value = err instanceof Error ? err : new Error(String(err))
-      return null
-    })
-    sitesLoading.value = false
-  }
-
-  function patchProgress(siteId: string, patch: Partial<SiteLoadProgress>): void {
-    const prev = progress.value[siteId]
-    progress.value = {
-      ...progress.value,
-      [siteId]: {
-        siteId,
-        stage: 'idle',
-        filesAttached: 0,
-        filesTotal: 0,
-        startedAt: prev?.startedAt ?? Date.now(),
-        ...prev,
-        ...patch,
-      },
-    }
-  }
-
-  function clearProgress(siteId?: string): void {
-    if (!siteId) {
-      progress.value = {}
-      return
-    }
-    const next = { ...progress.value }
-    delete next[siteId]
-    progress.value = next
-  }
-
-  // Lazy-load: defer refreshSites until something actually reads `sites`.
-  // Eager kick-off used to race host plugins that set auth via `setGscAuth`;
-  // first call would 401 and the rest of the session would silently degrade.
-  // Triggering on first read still needs to wait until hydration is done:
-  // `refreshSites()` flips `sitesLoading` synchronously, and doing that during
-  // the client's first render makes the sidebar disagree with SSR markup.
-  let kickedOff = false
-  function maybeKickOff(): void {
-    if (kickedOff || !import.meta.client)
-      return
-    kickedOff = true
-    const start = (): void => {
-      void refreshSites()
-    }
-    const nuxtApp = useNuxtApp()
-    if (nuxtApp.isHydrating)
-      onNuxtReady(start)
-    else
-      queueMicrotask(start)
-  }
-  const lazySites = computed<SiteListItem[] | null>(() => {
-    maybeKickOff()
-    return sites.value
-  })
-
-  return {
-    sites: lazySites as Readonly<Ref<SiteListItem[] | null>> as unknown as Ref<SiteListItem[] | null>,
-    sitesLoading: sitesLoading as Readonly<Ref<boolean>>,
-    sitesError: sitesError as Readonly<Ref<Error | null>>,
-    refreshSites,
-    progress: progress as Readonly<Ref<Record<string, SiteLoadProgress>>>,
-    patchProgress,
-    clearProgress,
-  }
-}

package/app/composables/useGscAnalyticsClient.ts

@@ -1,9 +0,0 @@
-// Reader for the layer's `AnalyticsClient`. Built once per NuxtApp by the
-// layer plugin and provided as `$gscAnalyticsClient`. Hosts override by
-// providing their own from a later plugin (e.g. to swap the SDK transport).
-
-import type { AnalyticsClient } from '@gscdump/sdk'
-
-export function useGscAnalyticsClient(): AnalyticsClient {
-  return useNuxtApp().$gscAnalyticsClient as AnalyticsClient
-}

package/app/composables/useGscAnalyticsConfig.ts

@@ -1,8 +0,0 @@
-// Typed reader for `runtimeConfig.public.analytics`. Single accessor so leaf
-// composables stop re-typing the cast and silently drift when keys are added.
-
-import type { GscAnalyticsRuntimeConfig } from '../../types'
-
-export function useGscAnalyticsConfig(): GscAnalyticsRuntimeConfig {
-  return useRuntimeConfig().public.analytics as unknown as GscAnalyticsRuntimeConfig
-}