@gscdump/engine-sqlite 3.4.4 → 3.6.0

package/README.md

@@ -4,11 +4,10 @@
 [![npm downloads](https://img.shields.io/npm/dm/@gscdump/engine-sqlite?color=yellow)](https://npm.chart.dev/@gscdump/engine-sqlite)
 [![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)
 
-> SQLite / D1 engine adapter for `@gscdump/analysis` — typed analytics over sqlite-proxy executors (Cloudflare D1, libsql).
+Run typed analytics over SQLite or D1 through an async executor.
 
-Wraps any sqlite-proxy executor (`(sql, params) => rows`) as a `SqlQuerySource` bound to a tenant `siteId`. Driver glue only; the typed builder + raw-SQL plumbing lives in `@gscdump/engine/resolver`.
-
-Bundle: **5.3 kB / 1.4 kB gzipped**.
+`createSqliteQuerySource` wraps an executor as an `AnalysisQuerySource` scoped to a Site.
+The Engine resolver builds the SQL; your executor runs it.
 
 ## Install
 
@@ -20,18 +19,14 @@ npm install @gscdump/engine-sqlite @gscdump/engine drizzle-orm
 
 ```ts
 import {
-  aggClicks,
   aggCtr,
-  aggImpressions,
-  aggPosition,
   compileSqlite,
-  createSqliteInsightRunner,
   gsc_keywords,
   sql,
 } from '@gscdump/engine-sqlite'
 
 const queryExpr = sql`
-  SELECT ${gsc_keywords.query} as keyword,
+  SELECT ${gsc_keywords.query} as query,
          SUM(${gsc_keywords.clicks}) as clicks,
          ${aggCtr(gsc_keywords)} as ctr
   FROM ${gsc_keywords}
@@ -40,7 +35,7 @@ const queryExpr = sql`
 `
 
 const { sql: compiledSql, params } = compileSqlite(queryExpr)
-const rows = await executor(compiledSql, params) // queryUserD1, libsql, ...
+const { rows } = await executor(compiledSql, params, 'all')
 ```
 
 ### Engine source for analyzer dispatch
@@ -51,39 +46,37 @@ import { createSqliteQuerySource } from '@gscdump/engine-sqlite'
 const source = createSqliteQuerySource({
   executor, // (sql, params, mode) => { rows }
   siteId,
-  regex: true, // hosts that expose REGEXP (D1, libsql, sqlite3+regexp)
+  regex: true, // Enable only if your executor supports REGEXP
 })
 ```
 
-Always import `sql` from `@gscdump/engine-sqlite` — not `drizzle-orm` directly — so consumers bind to the package's drizzle-orm instance and avoid cross-install `SQL<unknown>` mismatches.
+Import `sql` from `@gscdump/engine-sqlite` so it uses the same Drizzle instance as the package.
+This avoids `SQL<unknown>` type mismatches between installations.
 
 ## Exports
 
-- `createSqliteQuerySource({ executor, siteId, regex? })` — builds an `AnalysisQuerySource`.
-- `createSqliteInsightRunner({ executor })` — sqlite-proxy drizzle adapter.
-- `compileSqlite(sql)` — compile to `{ sql, params }` for any HTTP executor.
-- `aggClicks` / `aggImpressions` / `aggCtr` / `aggPosition` — aggregate helpers.
-- `scopeFor(table, { siteId, window })` / `mergeScope()` — tenant scope predicates.
-- `gsc_pages` / `gsc_keywords` / `gsc_page_keywords` / `gsc_countries` / `gsc_devices` / `schema` — drizzle schema mirroring `gscdump/analytics` `SCHEMAS`.
-- `sqliteResolverAdapter` / `createSqliteResolverAdapter` / `probeSqliteRegex` — dialect adapter for the resolver kit.
+- `createSqliteQuerySource({ executor, siteId, regex? })` : builds an `AnalysisQuerySource`.
+- `createSqliteInsightRunner({ executor })` : sqlite-proxy drizzle adapter.
+- `compileSqlite(sql)` : compile to `{ sql, params }` for any HTTP executor.
+- `aggClicks` / `aggImpressions` / `aggCtr` / `aggPosition` : aggregate helpers.
+- `scopeFor(table, { siteId, window })` / `mergeScope()` : tenant scope predicates.
+- `gsc_pages` / `gsc_keywords` / `gsc_page_keywords` / `gsc_countries` / `gsc_devices` / `gsc_query_dim` / `schema` : drizzle schema mirroring `@gscdump/engine/schema`.
+- `sqliteResolverAdapter` / `createSqliteResolverAdapter` / `probeSqliteRegex` : dialect adapter for the resolver kit.
 - `resolveWindow` (re-exported from `@gscdump/engine/period`).
 
-## D1 Analytics Table Status
+## Storage tables
 
-The `gsc_*` analytics tables remain a supported compatibility surface. The
-2026-06-29 Iceberg migration audit found active package exports, resolver tests,
-and docs for `gsc_pages`, `gsc_keywords`, `gsc_page_keywords`, `gsc_countries`,
-and `gsc_devices`. Do not remove these tables as part of the Iceberg/canonical
-migration. A future retirement should be staged behind a consumer usage audit,
-dual-read/shadow-read checks, and a release note that names the replacement
-Iceberg/R2 SQL path.
+The `gsc_*` tables remain exported for SQLite and D1 consumers.
+This adapter also exports `createD1ManifestStore` and its `r2*` manifest tables.
+Your application owns table creation, migrations, and data ingestion.
+The CLI uses a Parquet Store; it does not sync into these SQLite tables.
 
 ## Related
 
-- [`@gscdump/engine`](../engine) — Storage contracts + dialect-neutral resolver.
-- [`@gscdump/analysis`](../analysis) — Analyzer registry + dispatcher.
-- [`@gscdump/engine/node`](../engine) — Node DuckDB counterpart.
-- [`@gscdump/engine-duckdb-wasm`](../engine-duckdb-wasm) — Browser DuckDB-WASM counterpart.
+- [`@gscdump/engine`](../engine) : Storage contracts + dialect-neutral resolver.
+- [`@gscdump/analysis`](../analysis) : Analyzer registry + dispatcher.
+- [`@gscdump/engine/node`](../engine) : Node DuckDB counterpart.
+- [`@gscdump/engine-duckdb-wasm`](../engine-duckdb-wasm) : Browser DuckDB-WASM counterpart.
 
 ## License
 

package/dist/metrics.d.mts

@@ -1,8 +1,7 @@
 import { gsc_countries, gsc_devices, gsc_keywords, gsc_page_keywords, gsc_pages } from "./schema.mjs";
 import { SQL } from "drizzle-orm";
 type MetricTable = typeof gsc_pages | typeof gsc_keywords | typeof gsc_countries | typeof gsc_devices | typeof gsc_page_keywords;
-declare function aggClicks(t: MetricTable): SQL;
-declare function aggImpressions(t: MetricTable): SQL;
-declare function aggCtr(t: MetricTable): SQL;
-declare function aggPosition(t: MetricTable): SQL;
-export { aggClicks, aggCtr, aggImpressions, aggPosition };
+export declare function aggClicks(t: MetricTable): SQL;
+export declare function aggImpressions(t: MetricTable): SQL;
+export declare function aggCtr(t: MetricTable): SQL;
+export declare function aggPosition(t: MetricTable): SQL;

package/dist/query-source.d.mts

@@ -1,11 +1,10 @@
 import { SqliteRowExecutor } from "./runner.mjs";
 import { AnalysisQuerySource } from "@gscdump/engine/source";
-type SqliteQueryExecutor = SqliteRowExecutor;
-interface SqliteQuerySourceOptions {
+export type SqliteQueryExecutor = SqliteRowExecutor;
+export interface SqliteQuerySourceOptions {
   executor: SqliteQueryExecutor;
   siteId: string | number;
   /** Override for hosts that expose REGEXP (D1, libsql, sqlite3+regexp). */
   regex?: boolean;
 }
-declare function createSqliteQuerySource(config: SqliteQuerySourceOptions): AnalysisQuerySource;
-export { SqliteQueryExecutor, SqliteQuerySourceOptions, createSqliteQuerySource };
+export declare function createSqliteQuerySource(config: SqliteQuerySourceOptions): AnalysisQuerySource;

package/dist/r2-manifest-schema.d.mts

@@ -1,4 +1,4 @@
-declare const r2Manifest: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export declare const r2Manifest: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "r2_manifest";
   schema: undefined;
   columns: {
@@ -213,9 +213,9 @@ declare const r2Manifest: import("drizzle-orm/sqlite-core").SQLiteTableWithColum
   };
   dialect: "sqlite";
 }>;
-type R2ManifestInsert = typeof r2Manifest.$inferInsert;
-type R2ManifestSelect = typeof r2Manifest.$inferSelect;
-declare const r2WriteErrors: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export type R2ManifestInsert = typeof r2Manifest.$inferInsert;
+export type R2ManifestSelect = typeof r2Manifest.$inferSelect;
+export declare const r2WriteErrors: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "r2_write_errors";
   schema: undefined;
   columns: {
@@ -334,9 +334,9 @@ declare const r2WriteErrors: import("drizzle-orm/sqlite-core").SQLiteTableWithCo
   };
   dialect: "sqlite";
 }>;
-type R2WriteErrorInsert = typeof r2WriteErrors.$inferInsert;
-type R2WriteErrorSelect = typeof r2WriteErrors.$inferSelect;
-declare const r2ShadowDiffs: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export type R2WriteErrorInsert = typeof r2WriteErrors.$inferInsert;
+export type R2WriteErrorSelect = typeof r2WriteErrors.$inferSelect;
+export declare const r2ShadowDiffs: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "r2_shadow_diffs";
   schema: undefined;
   columns: {
@@ -439,9 +439,9 @@ declare const r2ShadowDiffs: import("drizzle-orm/sqlite-core").SQLiteTableWithCo
   };
   dialect: "sqlite";
 }>;
-type R2ShadowDiffInsert = typeof r2ShadowDiffs.$inferInsert;
-type R2ShadowDiffSelect = typeof r2ShadowDiffs.$inferSelect;
-declare const r2Locks: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export type R2ShadowDiffInsert = typeof r2ShadowDiffs.$inferInsert;
+export type R2ShadowDiffSelect = typeof r2ShadowDiffs.$inferSelect;
+export declare const r2Locks: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "r2_locks";
   schema: undefined;
   columns: {
@@ -512,9 +512,9 @@ declare const r2Locks: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<
   };
   dialect: "sqlite";
 }>;
-type R2LockInsert = typeof r2Locks.$inferInsert;
-type R2LockSelect = typeof r2Locks.$inferSelect;
-declare const r2Watermarks: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export type R2LockInsert = typeof r2Locks.$inferInsert;
+export type R2LockSelect = typeof r2Locks.$inferSelect;
+export declare const r2Watermarks: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "r2_watermarks";
   schema: undefined;
   columns: {
@@ -617,9 +617,9 @@ declare const r2Watermarks: import("drizzle-orm/sqlite-core").SQLiteTableWithCol
   };
   dialect: "sqlite";
 }>;
-type R2WatermarkInsert = typeof r2Watermarks.$inferInsert;
-type R2WatermarkSelect = typeof r2Watermarks.$inferSelect;
-declare const r2SyncStates: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export type R2WatermarkInsert = typeof r2Watermarks.$inferInsert;
+export type R2WatermarkSelect = typeof r2Watermarks.$inferSelect;
+export declare const r2SyncStates: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "r2_sync_states";
   schema: undefined;
   columns: {
@@ -770,6 +770,5 @@ declare const r2SyncStates: import("drizzle-orm/sqlite-core").SQLiteTableWithCol
   };
   dialect: "sqlite";
 }>;
-type R2SyncStateInsert = typeof r2SyncStates.$inferInsert;
-type R2SyncStateSelect = typeof r2SyncStates.$inferSelect;
-export { R2LockInsert, R2LockSelect, R2ManifestInsert, R2ManifestSelect, R2ShadowDiffInsert, R2ShadowDiffSelect, R2SyncStateInsert, R2SyncStateSelect, R2WatermarkInsert, R2WatermarkSelect, R2WriteErrorInsert, R2WriteErrorSelect, r2Locks, r2Manifest, r2ShadowDiffs, r2SyncStates, r2Watermarks, r2WriteErrors };
+export type R2SyncStateInsert = typeof r2SyncStates.$inferInsert;
+export type R2SyncStateSelect = typeof r2SyncStates.$inferSelect;

package/dist/r2-manifest-store.d.mts

@@ -9,6 +9,5 @@ interface AnalyticsManifestSchema extends Schema {
   r2Watermarks: typeof r2Watermarks;
 }
 type AnalyticsManifestRelations = ExtractTablesWithRelations<Record<string, never>, AnalyticsManifestSchema>;
-type AnalyticsManifestDb = DrizzleD1Database<AnalyticsManifestRelations>;
-declare function createD1ManifestStore(db: AnalyticsManifestDb): ManifestStore;
-export { AnalyticsManifestDb, createD1ManifestStore };
+export type AnalyticsManifestDb = DrizzleD1Database<AnalyticsManifestRelations>;
+export declare function createD1ManifestStore(db: AnalyticsManifestDb): ManifestStore;

package/dist/resolver-adapter.d.mts

@@ -1,20 +1,20 @@
 import { schema } from "./schema.mjs";
 import { SqliteRowExecutor } from "./runner.mjs";
 import { ResolverAdapter } from "@gscdump/engine/resolver";
-type TableKey = keyof typeof schema;
-interface CreateSqliteResolverAdapterOptions {
+export type TableKey = keyof typeof schema;
+export interface CreateSqliteResolverAdapterOptions {
   regex?: boolean;
 }
-declare function createSqliteResolverAdapter(options?: CreateSqliteResolverAdapterOptions): ResolverAdapter<TableKey>;
-declare const sqliteResolverAdapter: ResolverAdapter<"gsc_pages" | "gsc_keywords" | "gsc_countries" | "gsc_devices" | "gsc_page_keywords" | "gsc_search_appearance" | "gsc_search_appearance_pages" | "gsc_search_appearance_queries" | "gsc_search_appearance_page_queries" | "gsc_hourly_pages" | "gsc_query_dim">;
+export declare function createSqliteResolverAdapter(options?: CreateSqliteResolverAdapterOptions): ResolverAdapter<TableKey>;
+export declare const sqliteResolverAdapter: ResolverAdapter<"gsc_pages" | "gsc_keywords" | "gsc_countries" | "gsc_devices" | "gsc_page_keywords" | "gsc_search_appearance" | "gsc_search_appearance_pages" | "gsc_search_appearance_queries" | "gsc_search_appearance_page_queries" | "gsc_hourly_pages" | "gsc_query_dim">;
 /**
  * One-shot probe that detects whether the host SQLite has a working REGEXP
  * function. SQLite ships REGEXP as a no-op stub by default; D1, libsql, and
  * sqlite3 with the regexp extension register a real implementation. Probe
  * once at adapter construction so per-query plan-time gating is honest.
  */
-declare function probeSqliteRegex(executor: SqliteRowExecutor): Promise<boolean>;
-interface CreateSqliteResolverAdapterFromExecutorOptions {
+export declare function probeSqliteRegex(executor: SqliteRowExecutor): Promise<boolean>;
+export interface CreateSqliteResolverAdapterFromExecutorOptions {
   executor: SqliteRowExecutor;
 }
 /**
@@ -23,5 +23,4 @@ interface CreateSqliteResolverAdapterFromExecutorOptions {
  * the manual `createSqliteResolverAdapter({ regex })` whenever you have
  * an executor handy.
  */
-declare function createSqliteResolverAdapterFromExecutor(options: CreateSqliteResolverAdapterFromExecutorOptions): Promise<ResolverAdapter<TableKey>>;
-export { CreateSqliteResolverAdapterFromExecutorOptions, CreateSqliteResolverAdapterOptions, TableKey, createSqliteResolverAdapter, createSqliteResolverAdapterFromExecutor, probeSqliteRegex, sqliteResolverAdapter };
+export declare function createSqliteResolverAdapterFromExecutor(options: CreateSqliteResolverAdapterFromExecutorOptions): Promise<ResolverAdapter<TableKey>>;

package/dist/runner.d.mts

@@ -4,14 +4,14 @@ import { ScopedRunnerOptions, TableScope } from "@gscdump/engine/scope";
 import { ExtractTablesWithRelations, Schema } from "drizzle-orm/relations";
 import { SqliteRemoteDatabase } from "drizzle-orm/sqlite-proxy";
 type SchemaRelations<TSchema extends Schema> = ExtractTablesWithRelations<Record<string, never>, TSchema>;
-declare function compileSqlite(query: SQL): {
+export declare function compileSqlite(query: SQL): {
   sql: string;
   params: unknown[];
 };
-type SqliteRowExecutor = (sql: string, params: unknown[], method: 'run' | 'all' | 'values' | 'get') => Promise<{
+export type SqliteRowExecutor = (sql: string, params: unknown[], method: 'run' | 'all' | 'values' | 'get') => Promise<{
   rows: unknown[];
 }>;
-interface SqliteInsightRunnerOptions<TSchema extends Schema = Schema$1> {
+export interface SqliteInsightRunnerOptions<TSchema extends Schema = Schema$1> {
   executor: SqliteRowExecutor;
   logger?: boolean;
   /**
@@ -27,10 +27,10 @@ interface SqliteInsightRunnerOptions<TSchema extends Schema = Schema$1> {
    */
   schema?: TSchema;
 }
-interface SqliteInsightRunner<TSchema extends Schema = Schema$1> {
+export interface SqliteInsightRunner<TSchema extends Schema = Schema$1> {
   db: SqliteRemoteDatabase<SchemaRelations<TSchema>>;
 }
-declare function createSqliteInsightRunner<TSchema extends Schema = Schema$1>(opts: SqliteInsightRunnerOptions<TSchema>): SqliteInsightRunner<TSchema>;
-declare const scopeFor: (table: "gsc_pages" | "gsc_keywords" | "gsc_countries" | "gsc_devices" | "gsc_page_keywords" | "gsc_search_appearance" | "gsc_search_appearance_pages" | "gsc_search_appearance_queries" | "gsc_search_appearance_page_queries" | "gsc_hourly_pages" | "gsc_query_dim", opts: ScopedRunnerOptions) => TableScope;
-declare const mergeScope: typeof import("@gscdump/engine/scope").mergeScope;
-export { type ScopedRunnerOptions, SqliteInsightRunner, SqliteInsightRunnerOptions, SqliteRowExecutor, type TableScope, compileSqlite, createSqliteInsightRunner, mergeScope, scopeFor };
+export declare function createSqliteInsightRunner<TSchema extends Schema = Schema$1>(opts: SqliteInsightRunnerOptions<TSchema>): SqliteInsightRunner<TSchema>;
+export declare const scopeFor: (table: "gsc_pages" | "gsc_keywords" | "gsc_countries" | "gsc_devices" | "gsc_page_keywords" | "gsc_search_appearance" | "gsc_search_appearance_pages" | "gsc_search_appearance_queries" | "gsc_search_appearance_page_queries" | "gsc_hourly_pages" | "gsc_query_dim", opts: ScopedRunnerOptions) => TableScope;
+export declare const mergeScope: typeof import("@gscdump/engine/scope").mergeScope;
+export type { ScopedRunnerOptions, TableScope };

package/dist/schema.d.mts

@@ -6,7 +6,7 @@
  * aggregation. Mirror of gscdump.com/database/user/schema.ts relative to
  * the columns analytics queries actually read.
  */
-declare const gsc_pages: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export declare const gsc_pages: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "gsc_pages";
   schema: undefined;
   columns: {
@@ -218,7 +218,7 @@ declare const gsc_pages: import("drizzle-orm/sqlite-core").SQLiteTableWithColumn
   };
   dialect: "sqlite";
 }>;
-declare const gsc_keywords: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export declare const gsc_keywords: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "gsc_keywords";
   schema: undefined;
   columns: {
@@ -430,7 +430,7 @@ declare const gsc_keywords: import("drizzle-orm/sqlite-core").SQLiteTableWithCol
   };
   dialect: "sqlite";
 }>;
-declare const gsc_countries: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export declare const gsc_countries: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "gsc_countries";
   schema: undefined;
   columns: {
@@ -642,7 +642,7 @@ declare const gsc_countries: import("drizzle-orm/sqlite-core").SQLiteTableWithCo
   };
   dialect: "sqlite";
 }>;
-declare const gsc_devices: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export declare const gsc_devices: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "gsc_devices";
   schema: undefined;
   columns: {
@@ -854,7 +854,7 @@ declare const gsc_devices: import("drizzle-orm/sqlite-core").SQLiteTableWithColu
   };
   dialect: "sqlite";
 }>;
-declare const gsc_page_keywords: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export declare const gsc_page_keywords: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "gsc_page_keywords";
   schema: undefined;
   columns: {
@@ -1082,7 +1082,7 @@ declare const gsc_page_keywords: import("drizzle-orm/sqlite-core").SQLiteTableWi
   };
   dialect: "sqlite";
 }>;
-declare const gsc_query_dim: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+export declare const gsc_query_dim: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
   name: "gsc_query_dim";
   schema: undefined;
   columns: {
@@ -1201,7 +1201,7 @@ declare const gsc_query_dim: import("drizzle-orm/sqlite-core").SQLiteTableWithCo
   };
   dialect: "sqlite";
 }>;
-declare const schema: {
+export declare const schema: {
   gsc_pages: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
     name: "gsc_pages";
     schema: undefined;
@@ -3538,5 +3538,4 @@ declare const schema: {
     dialect: "sqlite";
   }>;
 };
-type Schema = typeof schema;
-export { Schema, gsc_countries, gsc_devices, gsc_keywords, gsc_page_keywords, gsc_pages, gsc_query_dim, schema };
+export type Schema = typeof schema;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/engine-sqlite",
   "type": "module",
-  "version": "3.4.4",
+  "version": "3.6.0",
   "description": "SQLite / D1 engine adapter for @gscdump/analysis — typed analytics over sqlite-proxy executors (Cloudflare D1, libsql).",
   "author": {
     "name": "Harlan Wilton",
@@ -44,11 +44,11 @@
     "drizzle-orm": "1.0.0-rc.4"
   },
   "dependencies": {
-    "@gscdump/engine": "^3.4.4"
+    "@gscdump/engine": "^3.6.0"
   },
   "devDependencies": {
     "drizzle-orm": "1.0.0-rc.4",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "build": "obuild",