@voltro/plugin-duckdb 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { AggregateQuery } from '@voltro/runtime';
+import { AnalyticsBucket } from '@voltro/runtime';
+import { AnalyticsEvent } from '@voltro/runtime';
+import { AnalyticsSinkSpec } from '@voltro/runtime';
+import { AnalyticsTopEntry } from '@voltro/runtime';
+import { TimeseriesQuery } from '@voltro/runtime';
+import { TopNQuery } from '@voltro/runtime';
+
+export { AggregateQuery }
+
+export { AnalyticsBucket }
+
+export { AnalyticsEvent }
+
+export { AnalyticsTopEntry }
+
+/**
+ * Construct the spec. `build()` returns the sink wrapper; `initialize`
+ * opens the DuckDB connection + creates the events table; `dispose`
+ * closes the connection + instance at shutdown. All three share a
+ * `state` holder so methods can grab the connection once it's been
+ * filled in, and teardown can release it.
+ */
+export declare const duckdbAnalytics: (options?: DuckdbAnalyticsOptions) => AnalyticsSinkSpec;
+
+export declare interface DuckdbAnalyticsOptions extends DuckdbSinkOptions {
+}
+
+declare interface DuckdbSinkOptions {
+    readonly path?: string;
+    /**
+     * Reactive tables to CDC-mirror into DuckDB. Each table gets a
+     * `voltro_mirror_<table>` table (`{ id, data }`) so analytical
+     * queries can JOIN events against live user data:
+     *
+     *   SELECT json_extract_string(m.data, '$.tier'), COUNT(*)
+     *   FROM voltro_events e
+     *   JOIN voltro_mirror_users m ON m.id = e.subject_id
+     *   GROUP BY 1
+     *
+     * Empty / omitted → events-only.
+     */
+    readonly mirrorTables?: ReadonlyArray<string>;
+    /** Primary-key column on the mirrored source rows. Default `'id'`. */
+    readonly mirrorPrimaryKey?: string;
+}
+
+export { TimeseriesQuery }
+
+export { TopNQuery }
+
+export { }

package/dist/index.js

@@ -0,0 +1,203 @@
+import { Effect as e, Option as t } from "effect";
+import { AnalyticsError as n } from "@voltro/runtime";
+//#region src/sink.ts
+var r = "duckdb", i = "voltro_events", a = null, o = () => a === null ? e.tryPromise({
+	try: async () => {
+		let e = await import("@duckdb/node-api");
+		return a = e, e;
+	},
+	catch: (e) => new n({
+		provider: r,
+		operation: "loadNativeModule",
+		cause: "@duckdb/node-api could not be loaded — the native binary for this platform may be missing (it is an optionalDependency). " + (e instanceof Error ? `${e.name}: ${e.message}` : String(e))
+	})
+}) : e.succeed(a), s = (e) => new a.DuckDBTimestampValue(BigInt(e.getTime()) * 1000n), c = (e) => `voltro_mirror_${e}`, l = /^[A-Za-z_][A-Za-z0-9_]*$/, u = (e, t, i) => {
+	if (!l.test(t)) throw new n({
+		provider: r,
+		operation: e,
+		cause: `invalid ${i} ${JSON.stringify(t)} — must match ${l.source} (letters, digits, underscore; no dots/quotes/spaces)`
+	});
+	return t;
+}, d = /['\\]/, f = (e) => {
+	for (let t = 0; t < e.length; t++) if (e.charCodeAt(t) < 32) return !0;
+	return !1;
+}, p = (e, t) => {
+	if (d.test(t) || f(t)) throw new n({
+		provider: r,
+		operation: e,
+		cause: `invalid property key ${JSON.stringify(t)} — must not contain quotes, backslashes, or control characters`
+	});
+	return t;
+}, m = `
+  CREATE SEQUENCE IF NOT EXISTS voltro_events_id_seq;
+  CREATE TABLE IF NOT EXISTS ${i} (
+    id          BIGINT PRIMARY KEY DEFAULT nextval('voltro_events_id_seq'),
+    name        VARCHAR NOT NULL,
+    subject_id  VARCHAR,
+    tenant_id   VARCHAR,
+    properties  JSON NOT NULL DEFAULT '{}',
+    occurred_at TIMESTAMP NOT NULL DEFAULT now()
+  );
+`.trim(), h = (i) => (a) => a.pipe(e.catchSomeDefect((r) => r instanceof n ? t.some(e.fail(r)) : t.none()), e.mapError((e) => e instanceof n ? e : new n({
+	provider: r,
+	operation: i,
+	cause: e instanceof Error ? `${e.name}: ${e.message}` : String(e)
+}))), g = (t) => t.conn === null ? e.fail(new n({
+	provider: r,
+	operation: "ensureConn",
+	cause: "connection not initialized — spec.initialize must run before queries"
+})) : e.succeed(t.conn), _ = (e, t) => `date_trunc('${t}', ${e})`, v = (e, t) => `json_extract_string(properties, '$.${p(e, t)}')`, y = (e, t) => `TRY_CAST(json_extract_string(properties, '$.${p(e, t)}') AS DOUBLE)`, b = (e, t) => t === "count" ? "COUNT(*)" : t === "unique" ? "COUNT(DISTINCT subject_id)" : "sum" in t ? `COALESCE(SUM(${y(e, t.sum)}), 0)` : `AVG(${y(e, t.avg)})`, x = (e, t) => t === "count" ? "COUNT(*)" : `COALESCE(SUM(${y(e, t.sum)}), 0)`, S = (e, t, n, r, i) => {
+	let { VARCHAR: o, TIMESTAMP: c } = a, l = [], u = [], d = [];
+	if (d.push("name = ?"), l.push(t), u.push(o), d.push("occurred_at >= ?"), l.push(s(n.from)), u.push(c), d.push("occurred_at < ?"), l.push(s(n.to ?? /* @__PURE__ */ new Date())), u.push(c), i != null && (d.push("tenant_id = ?"), l.push(i), u.push(o)), r !== void 0) for (let [t, n] of Object.entries(r)) d.push(`${v(e, t)} = ?`), l.push(String(n)), u.push(o);
+	return {
+		sql: d.join(" AND "),
+		params: l,
+		types: u
+	};
+}, C = (t, n, r) => {
+	let i = /* @__PURE__ */ new Set(), o = (n, r) => e.gen(function* () {
+		if (i.has(r)) return;
+		u(n, r, "mirror table name");
+		let a = yield* g(t), o = c(r);
+		yield* e.tryPromise({
+			try: () => a.run(`CREATE TABLE IF NOT EXISTS ${o} (id VARCHAR PRIMARY KEY, data JSON NOT NULL)`),
+			catch: (e) => e
+		}), i.add(r);
+	});
+	return {
+		tables: n,
+		primaryKey: r,
+		upsert: (n, i) => e.gen(function* () {
+			yield* o("mirror.upsert", n);
+			let s = yield* g(t), { VARCHAR: l } = a, u = c(n), d = String(i[r]), f = JSON.stringify(i);
+			yield* e.tryPromise({
+				try: () => s.run(`INSERT INTO ${u} (id, data) VALUES (?, ?::JSON) ON CONFLICT (id) DO UPDATE SET data = EXCLUDED.data`, [d, f], [l, l]),
+				catch: (e) => e
+			});
+		}).pipe(h("mirror.upsert")),
+		remove: (n, r) => e.gen(function* () {
+			yield* o("mirror.remove", n);
+			let i = yield* g(t), { VARCHAR: s } = a, l = c(n), u = String(r);
+			yield* e.tryPromise({
+				try: () => i.run(`DELETE FROM ${l} WHERE id = ?`, [u], [s]),
+				catch: (e) => e
+			});
+		}).pipe(h("mirror.remove"))
+	};
+}, w = (t, n) => {
+	let o = n.mirrorTables ?? [], c = o.length > 0 ? C(t, o, n.mirrorPrimaryKey ?? "id") : void 0;
+	return {
+		info: {
+			provider: r,
+			capabilities: {
+				track: !0,
+				aggregate: !0,
+				timeseries: !0,
+				topN: !0,
+				mirror: c !== void 0
+			},
+			detail: {
+				path: n.path ?? ":memory:",
+				...o.length > 0 ? { mirrorTables: o } : {}
+			}
+		},
+		track: (n) => e.gen(function* () {
+			let r = yield* g(t), { VARCHAR: o, TIMESTAMP: c } = a, l = n.occurredAt ?? /* @__PURE__ */ new Date(), u = JSON.stringify(n.properties), d = n.subjectId ?? null, f = n.tenantId ?? null;
+			yield* e.tryPromise({
+				try: () => r.run(`INSERT INTO ${i} (name, subject_id, tenant_id, properties, occurred_at) VALUES (?, ?, ?, ?::JSON, ?)`, [
+					n.name,
+					d,
+					f,
+					u,
+					s(l)
+				], [
+					o,
+					o,
+					o,
+					o,
+					c
+				]),
+				catch: (e) => e
+			});
+		}).pipe(h("track")),
+		aggregate: (n) => e.gen(function* () {
+			let r = yield* g(t), a = S("aggregate", n.event, n.range, n.filter, n.tenantId), o = `SELECT ${b("aggregate", n.metric)} AS value FROM ${i} WHERE ${a.sql}`, s = (yield* e.tryPromise({
+				try: () => r.runAndReadAll(o, a.params, a.types),
+				catch: (e) => e
+			})).getRowObjectsJS()[0]?.value ?? 0;
+			return typeof s == "number" ? s : Number(s ?? 0);
+		}).pipe(h("aggregate")),
+		timeseries: (n) => e.gen(function* () {
+			let r = yield* g(t), a = S("timeseries", n.event, n.range, n.filter, n.tenantId), o = _("occurred_at", n.bucket), s = `
+        SELECT ${o} AS bucket_start, ${b("timeseries", n.metric)} AS value
+        FROM ${i}
+        WHERE ${a.sql}
+        GROUP BY ${o}
+        ORDER BY ${o} ASC
+      `;
+			return (yield* e.tryPromise({
+				try: () => r.runAndReadAll(s, a.params, a.types),
+				catch: (e) => e
+			})).getRowObjectsJS().map((e) => ({
+				bucketStart: e.bucket_start instanceof Date ? e.bucket_start : new Date(e.bucket_start),
+				value: typeof e.value == "number" ? e.value : Number(e.value ?? 0)
+			}));
+		}).pipe(h("timeseries")),
+		topN: (n) => e.gen(function* () {
+			let r = yield* g(t), a = S("topN", n.event, n.range, n.filter, n.tenantId), o = Math.max(1, Math.floor(n.n)), s = v("topN", n.groupBy), c = `
+        SELECT ${s} AS key, ${x("topN", n.metric)} AS value
+        FROM ${i}
+        WHERE ${a.sql}
+        GROUP BY ${s}
+        ORDER BY value DESC
+        LIMIT ${o}
+      `;
+			return (yield* e.tryPromise({
+				try: () => r.runAndReadAll(c, a.params, a.types),
+				catch: (e) => e
+			})).getRowObjectsJS().filter((e) => e.key !== null).map((e) => ({
+				key: e.key,
+				value: typeof e.value == "number" ? e.value : Number(e.value ?? 0)
+			}));
+		}).pipe(h("topN")),
+		...c === void 0 ? {} : { mirror: c }
+	};
+}, T = (t, i) => e.gen(function* () {
+	if (t.conn !== null) return;
+	let a = yield* o(), s = yield* e.tryPromise({
+		try: async () => {
+			let e = await a.DuckDBInstance.create(i.path ?? ":memory:"), t = await e.connect();
+			return await t.run(m), {
+				instance: e,
+				connection: t
+			};
+		},
+		catch: (e) => new n({
+			provider: r,
+			operation: "initialize",
+			cause: e instanceof Error ? `${e.name}: ${e.message}` : String(e)
+		})
+	});
+	t.instance = s.instance, t.conn = s.connection;
+}), E = (t) => e.gen(function* () {
+	let { conn: n, instance: i } = t;
+	t.conn = null, t.instance = null, !(n === null && i === null) && (yield* e.try(() => {
+		n?.closeSync(), i?.closeSync();
+	}).pipe(e.catchAll((t) => e.logWarning("duckdb analytics sink teardown failed", {
+		provider: r,
+		err: t
+	}))));
+}), D = (e = {}) => {
+	let t = {
+		conn: null,
+		instance: null
+	};
+	return {
+		kind: "duckdb",
+		build: (n) => w(t, e),
+		initialize: () => T(t, e),
+		dispose: () => E(t)
+	};
+};
+//#endregion
+export { D as duckdbAnalytics };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@voltro/plugin-duckdb",
+  "version": "0.1.0",
+  "description": "Embedded DuckDB AnalyticsSink. Runs DuckDB in-process for real OLAP performance without an external service. Events land in a DuckDB column-store table; aggregate / timeseries / topN queries execute vectorized.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/runtime": "0.1.0"
+  },
+  "optionalDependencies": {
+    "@duckdb/node-api": "1.5.4-r.1"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}