@gscdump/engine-duckdb-wasm 0.40.2 → 1.0.1

package/README.md

@@ -23,19 +23,14 @@ import {
   attachParquetUrlTables,
   bootDuckDBWasm,
   createInsightRunner,
-  resolveWindow,
-  scopeFor,
-  strikingMomentum,
 } from '@gscdump/engine-duckdb-wasm'
 
 const { db, conn } = await bootDuckDBWasm()
 await attachParquetUrlTables(conn, { tables: [{ name: 'queries', url: '/r2/queries.parquet' }] })
 
-const runner = createInsightRunner({ db, conn })
-const window = resolveWindow({ preset: 'last-30d', comparison: 'prev-period' })
-const scope = scopeFor('queries', { siteId, window })
-
-const rows = await strikingMomentum(runner, { ...scope, limit: 50 })
+const runner = await createInsightRunner({ db, conn })
+const client = await runner.client
+const rows = await client.query('SELECT query, clicks, impressions FROM queries LIMIT 50')
 ```
 
 ## Browser Parquet Attachment Strategy
@@ -73,7 +68,6 @@ instead.
 - `createInsightRunner({ db, conn })` — drizzle-orm handle for typed `.select()` / window functions, with `sql\`...\`` raw escape hatch.
 - `bootDuckDBWasm()` / `attachParquetTables()` / `attachParquetUrlTables()` / `attachSingleTable()` / `createBrowserAnalysisRuntime()` / `createDuckDBBundlesFromBase()` / `listAttachedTables()` — browser runtime primitives.
 - `attachOpfsParquetTables()` / `readOpfsSnapshotFile()` / `estimateOpfsStorage()` / `requestPersistentStorage()` / `clearOpfsSnapshotCache()` — OPFS-backed parquet cache.
-- `strikingMomentum(runner, options)` — first-class browser insight.
 - `scopeFor(table, { siteId, window })` / `mergeScope()` — tenant scope predicates.
 - `pages` / `queries` / `page_queries` / `countries` / `dates` / `hourly_pages` / `schema` — drizzle schema mirroring `gscdump/analytics` `SCHEMAS`. Drift fails loudly at module load.
 - `compileArchetypeSql()` / `tableForArchetype()` — archetype query compilation.
@@ -83,7 +77,7 @@ instead.
 ## Related
 
 - [`@gscdump/engine`](../engine) — Storage contracts + dialect-neutral resolver.
-- [`@gscdump/analysis`](../analysis) — Analyzer registry + `analyzeContentGap` (browser semantic).
+- [`@gscdump/analysis`](../analysis) — Portable analyzer registry and browser dispatch.
 - [`@gscdump/engine-sqlite`](../engine-sqlite) — SQLite / D1 counterpart.
 
 ## License

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import { Assume, DrizzleConfig, entityKind } from "drizzle-orm";
 import { PgAsyncDatabase, PgAsyncPreparedQuery, PgAsyncSession, PgDialect, PgQueryResultHKT } from "drizzle-orm/pg-core";
 import { AnyRelations, EmptyRelations, ExtractTablesWithRelations, Schema as Schema$1 } from "drizzle-orm/relations";
-import { DrizzleSchema as Schema, countries, dates, drizzleSchema as schema, hourly_pages, page_queries, pages, queries } from "@gscdump/engine/schema";
 import { ScopedRunnerOptions, TableScope } from "@gscdump/engine/scope";
+import { DrizzleSchema as Schema, countries, dates, drizzleSchema as schema, hourly_pages, page_queries, pages, queries } from "@gscdump/engine/schema";
 import { AnalyzerRegistry } from "@gscdump/engine/analyzer";
 import { Result } from "gscdump/result";
 import { ComparisonMode, ResolveWindowOptions, ResolvedWindow, WindowPreset, resolveWindow } from "@gscdump/engine/period";
@@ -41,49 +41,6 @@ interface DuckDBWasmDrizzleDatabase<TSchema extends Schema$1 = Record<string, ne
   $client: Promise<DuckDBWasmClient>;
 }
 declare function drizzle<TSchema extends Schema$1 = Record<string, never>, TRelations extends AnyRelations = SchemaRelations<TSchema>>(client: Promise<DuckDBWasmClient> | DuckDBWasmClient, config?: DrizzleConfig<TSchema, TRelations>): DuckDBWasmDrizzleDatabase<TSchema, TRelations>;
-interface InsightRunnerOptions {
-  db: AsyncDuckDB;
-  conn: AsyncDuckDBConnection;
-  logger?: boolean;
-}
-interface InsightRunner {
-  db: DuckDBWasmDrizzleDatabase<Schema>;
-  client: Promise<DuckDBWasmClient>;
-  close: () => Promise<void>;
-}
-declare function createInsightRunner(opts: InsightRunnerOptions): Promise<InsightRunner>;
-/**
- * Build a per-table predicate set from {siteId, window}. The returned
- * `wherePredicates` composes with user-level filters via `mergeScope`.
- *
- * Note: the current SCHEMAS don't include `site_id` on any table (snapshots
- * are already per-site), so `siteId` is a no-op for now — kept in the API
- * so consumers can add the predicate without an interface change when
- * multi-site snapshots land.
- */
-declare const scopeFor: (table: "pages" | "queries" | "countries" | "page_queries" | "dates" | "search_appearance" | "search_appearance_pages" | "search_appearance_queries" | "search_appearance_page_queries" | "hourly_pages", opts: ScopedRunnerOptions) => TableScope, mergeScope: typeof import("@gscdump/engine/scope").mergeScope;
-interface StrikingMomentumOptions {
-  /** Anchor date (YYYY-MM-DD). Defaults to today. */
-  anchor?: string;
-  /** Width of each window in days. Default 90. */
-  windowDays?: number;
-  /** Minimum impressions in the prior window for a row to qualify. Default 10. */
-  minPriorImpressions?: number;
-  /** Minimum impressions in the recent window. Default 50. */
-  minRecentImpressions?: number;
-  /** Result limit. Default 20. */
-  limit?: number;
-}
-interface StrikingMomentumRow {
-  query: string;
-  url: string;
-  recent_impr: number;
-  recent_pos: number;
-  prior_impr: number;
-  prior_pos: number;
-  momentum_score: number;
-}
-declare function strikingMomentum(runner: InsightRunner, opts?: StrikingMomentumOptions): Promise<StrikingMomentumRow[]>;
 /** A parquet data file to materialise into OPFS. */
 interface OpfsParquetFile {
   /** Same-origin URL carrying a signed size hint + short-lived access token. */
@@ -309,6 +266,27 @@ declare function overlayViewBody(args: {
   overlaySelect: string | null;
   materializeLake?: boolean;
 }): string | null;
+interface InsightRunnerOptions {
+  db: AsyncDuckDB;
+  conn: AsyncDuckDBConnection;
+  logger?: boolean;
+}
+interface InsightRunner {
+  db: DuckDBWasmDrizzleDatabase<Schema>;
+  client: Promise<DuckDBWasmClient>;
+  close: () => Promise<void>;
+}
+declare function createInsightRunner(opts: InsightRunnerOptions): Promise<InsightRunner>;
+/**
+ * Build a per-table predicate set from {siteId, window}. The returned
+ * `wherePredicates` composes with user-level filters via `mergeScope`.
+ *
+ * Note: the current SCHEMAS don't include `site_id` on any table (snapshots
+ * are already per-site), so `siteId` is a no-op for now — kept in the API
+ * so consumers can add the predicate without an interface change when
+ * multi-site snapshots land.
+ */
+declare const scopeFor: (table: "pages" | "queries" | "countries" | "page_queries" | "dates" | "search_appearance" | "search_appearance_pages" | "search_appearance_queries" | "search_appearance_page_queries" | "hourly_pages", opts: ScopedRunnerOptions) => TableScope, mergeScope: typeof import("@gscdump/engine/scope").mergeScope;
 interface QueryResult {
   rows: Record<string, unknown>[];
   queryMs: number;
@@ -514,4 +492,4 @@ declare function createBrowserAnalysisRuntime(boot: DuckDBWasmBootResult, option
   version?: number | string;
   attachedTables?: readonly string[];
 }): BrowserAnalysisRuntime;
-export { type AnalyzeResult, type AttachOpfsTablesOptions, type AttachParquetTablesOptions, type AttachParquetUrlTablesOptions, type AttachedTablesHandle, type BootDuckDBWasmOptions, type BrowserAnalysisRuntime, BrowserAttachBudgetExceededError, type BrowserAttachError, type BrowserParquetFile, type BrowserParquetTable, type BrowserParquetUrlTable, type ComparisonMode, type CompiledArchetypeSql, type DuckDBWasmBootResult, type DuckDBWasmClient, DuckDBWasmDatabase, type DuckDBWasmDrizzleDatabase, type InsightRunner, type InsightRunnerOptions, type OpfsAttachTiming, type OpfsAttachTimingStage, type OpfsAttachedHandle, type OpfsFileProgress, type OpfsParquetFile, type OpfsParquetTable, OpfsQuotaExceededError, type QueryResult, type ResolveWindowOptions, type ResolvedWindow, type Schema, type ScopedRunnerOptions, type StrikingMomentumOptions, type StrikingMomentumRow, type TableScope, type WindowPreset, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, isBrowserAttachError, mergeScope, overlayViewBody, page_queries, pages, queries, readOpfsSnapshotFile, requestPersistentStorage, resolveWindow, schema, scopeFor, strikingMomentum, tableForArchetype };
+export { type AnalyzeResult, type AttachOpfsTablesOptions, type AttachParquetTablesOptions, type AttachParquetUrlTablesOptions, type AttachedTablesHandle, type BootDuckDBWasmOptions, type BrowserAnalysisRuntime, BrowserAttachBudgetExceededError, type BrowserAttachError, type BrowserParquetFile, type BrowserParquetTable, type BrowserParquetUrlTable, type ComparisonMode, type CompiledArchetypeSql, type DuckDBWasmBootResult, type DuckDBWasmClient, DuckDBWasmDatabase, type DuckDBWasmDrizzleDatabase, type InsightRunner, type InsightRunnerOptions, type OpfsAttachTiming, type OpfsAttachTimingStage, type OpfsAttachedHandle, type OpfsFileProgress, type OpfsParquetFile, type OpfsParquetTable, OpfsQuotaExceededError, type QueryResult, type ResolveWindowOptions, type ResolvedWindow, type Schema, type ScopedRunnerOptions, type TableScope, type WindowPreset, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, isBrowserAttachError, mergeScope, overlayViewBody, page_queries, pages, queries, readOpfsSnapshotFile, requestPersistentStorage, resolveWindow, schema, scopeFor, tableForArchetype };

package/dist/index.mjs

@@ -1,10 +1,9 @@
 import { arrowToRows } from "@gscdump/engine/arrow";
-import { DefaultLogger, NoopLogger, entityKind, sql } from "drizzle-orm";
+import { DefaultLogger, NoopLogger, entityKind } from "drizzle-orm";
 import { PgAsyncDatabase, PgAsyncPreparedQuery, PgAsyncSession, PgDialect } from "drizzle-orm/pg-core";
 import { buildRelations } from "drizzle-orm/relations";
-import { toIsoDate } from "gscdump/dates";
-import { countries, dates, drizzleSchema as schema, hourly_pages, page_queries, pages, queries } from "@gscdump/engine/schema";
 import { createScopedHelpers } from "@gscdump/engine/scope";
+import { countries, dates, drizzleSchema as schema, hourly_pages, page_queries, pages, queries } from "@gscdump/engine/schema";
 import { runAnalyzerFromSource } from "@gscdump/engine/analyzer";
 import { pgResolverAdapter } from "@gscdump/engine/resolver";
 import { createAttachedTableSource } from "@gscdump/engine/source";
@@ -442,67 +441,6 @@ function drizzle(client, config = {}) {
 	db.$client = clientPromise;
 	return db;
 }
-async function strikingMomentum(runner, opts = {}) {
-	const windowDays = opts.windowDays ?? 90;
-	const anchor = opts.anchor ?? toIsoDate(/* @__PURE__ */ new Date());
-	const minPrior = opts.minPriorImpressions ?? 10;
-	const minRecent = opts.minRecentImpressions ?? 50;
-	const limit = opts.limit ?? 20;
-	const windowExpr = sql`
-    WITH pk AS (
-      SELECT
-        query,
-        url,
-        ${page_queries.date} AS date,
-        ${page_queries.impressions} AS impressions,
-        ${page_queries.sum_position} AS sum_position,
-        CASE
-          WHEN ${page_queries.date} >= (DATE ${sql.raw(`'${anchor}'`)} - INTERVAL ${sql.raw(`${windowDays}`)} DAY)
-          THEN 'recent' ELSE 'prior'
-        END AS period
-      FROM ${page_queries}
-      WHERE ${page_queries.date} >= (DATE ${sql.raw(`'${anchor}'`)} - INTERVAL ${sql.raw(`${windowDays * 2}`)} DAY)
-        AND ${page_queries.date} <  (DATE ${sql.raw(`'${anchor}'`)} + INTERVAL 1 DAY)
-    ),
-    agg AS (
-      SELECT
-        query, url, period,
-        SUM(impressions) AS impr,
-        SUM(sum_position) / NULLIF(SUM(impressions), 0) + 1 AS weighted_pos
-      FROM pk
-      GROUP BY query, url, period
-    ),
-    paired AS (
-      SELECT
-        query, url,
-        MAX(CASE WHEN period = 'recent' THEN impr END) AS recent_impr,
-        MAX(CASE WHEN period = 'recent' THEN weighted_pos END) AS recent_pos,
-        MAX(CASE WHEN period = 'prior' THEN impr END) AS prior_impr,
-        MAX(CASE WHEN period = 'prior' THEN weighted_pos END) AS prior_pos
-      FROM agg
-      GROUP BY query, url
-    ),
-    best AS (
-      SELECT
-        query, url, recent_impr, recent_pos, prior_impr, prior_pos,
-        ROW_NUMBER() OVER (PARTITION BY query ORDER BY recent_impr DESC NULLS LAST) AS rn
-      FROM paired
-      WHERE prior_impr >= ${minPrior} AND recent_impr >= ${minRecent}
-    )
-    SELECT
-      query, url,
-      recent_impr, recent_pos, prior_impr, prior_pos,
-      (prior_pos - recent_pos)
-        * LN(recent_impr + 1)
-        * CASE WHEN recent_pos BETWEEN 8 AND 20 THEN 1.5 ELSE 1.0 END
-      AS momentum_score
-    FROM best
-    WHERE rn = 1
-    ORDER BY momentum_score DESC NULLS LAST
-    LIMIT ${limit}
-  `;
-	return await runner.db.execute(windowExpr);
-}
 function createOpfsHandleRegistry(backend) {
 	const entries = /* @__PURE__ */ new Map();
 	const pending = /* @__PURE__ */ new Map();
@@ -1616,4 +1554,4 @@ function createBrowserAnalysisRuntime(boot, options = {}) {
 		}
 	};
 }
-export { BrowserAttachBudgetExceededError, DuckDBWasmDatabase, OpfsQuotaExceededError, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, isBrowserAttachError, mergeScope, overlayViewBody, page_queries, pages, queries, readOpfsSnapshotFile, requestPersistentStorage, resolveWindow, schema, scopeFor, strikingMomentum, tableForArchetype };
+export { BrowserAttachBudgetExceededError, DuckDBWasmDatabase, OpfsQuotaExceededError, attachOpfsParquetTables, attachParquetTables, attachParquetUrlTables, attachParquetUrlTablesResult, bootDuckDBWasm, browserAttachErrors, clearOpfsSnapshotCache, compileArchetypeSql, countries, createBrowserAnalysisRuntime, createClient, createInsightRunner, dates, drizzle, estimateOpfsStorage, hourly_pages, isBrowserAttachError, mergeScope, overlayViewBody, page_queries, pages, queries, readOpfsSnapshotFile, requestPersistentStorage, resolveWindow, schema, scopeFor, tableForArchetype };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine-duckdb-wasm",
   "type": "module",
-  "version": "0.40.2",
+  "version": "1.0.1",
   "description": "DuckDB-WASM engine adapter for @gscdump/analysis — typed browser analytics against parquet via R2.",
   "author": {
     "name": "Harlan Wilton",
@@ -33,10 +33,10 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "peerDependencies": {
-    "@duckdb/duckdb-wasm": "^1.32.0"
+    "@duckdb/duckdb-wasm": "^1.33.1-dev57.0"
   },
   "peerDependenciesMeta": {
     "@duckdb/duckdb-wasm": {
@@ -45,12 +45,12 @@
   },
   "dependencies": {
     "drizzle-orm": "1.0.0-rc.3",
-    "gscdump": "0.40.2",
-    "@gscdump/engine": "0.40.2",
-    "@gscdump/contracts": "0.40.2"
+    "@gscdump/contracts": "^1.0.1",
+    "@gscdump/engine": "^1.0.1",
+    "gscdump": "^1.0.1"
   },
   "devDependencies": {
-    "@duckdb/duckdb-wasm": "^1.32.0",
+    "@duckdb/duckdb-wasm": "1.33.1-dev57.0",
     "@vitest/browser": "^4.1.10",
     "@vitest/browser-playwright": "^4.1.10",
     "playwright": "^1.61.1",