@synode/adapter-bigquery 1.0.0

package/LICENSE

@@ -0,0 +1,35 @@
+Synode Proprietary License
+
+Copyright (c) 2026 Digitl Cloud GmbH. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of this software and associated documentation files (the
+"Software"), to use the Software for personal, internal, and commercial
+purposes, subject to the following conditions:
+
+1. PERMITTED USE. You may use, copy, and modify the Software for your own
+   personal, internal, or commercial purposes.
+
+2. NO REDISTRIBUTION. You may not distribute, publish, sublicense, or
+   otherwise make the Software or any derivative works available to third
+   parties, whether in source code or compiled form, free of charge or for
+   a fee.
+
+3. NO RESALE. You may not sell, rent, lease, or otherwise commercially
+   exploit the Software itself as a standalone product or as part of a
+   software distribution.
+
+4. NO HOSTING AS A SERVICE. You may not offer the Software to third parties
+   as a hosted, managed, or software-as-a-service product where the primary
+   value derives from the Software.
+
+5. ATTRIBUTION. You must retain this license notice and copyright notice in
+   all copies or substantial portions of the Software.
+
+6. NO WARRANTY. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+   IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES
+   OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+   OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @synode/adapter-bigquery
+
+BigQuery adapter for Synode. Import datasets from BigQuery tables and export generated events with automatic batching.
+
+## Install
+
+```bash
+npm install @synode/adapter-bigquery @google-cloud/bigquery
+```
+
+Requires `@synode/core` and `@google-cloud/bigquery` as peer dependencies.
+
+## Export (Writing Events)
+
+```ts
+import { generate } from '@synode/core';
+import { BigQueryAdapter } from '@synode/adapter-bigquery';
+
+const adapter = new BigQueryAdapter({
+  projectId: 'my-project',
+  datasetId: 'analytics',
+  tableId: 'events',
+  batchSize: 200,
+});
+
+await generate(journey, { users: 100, adapter });
+await adapter.close();
+```
+
+### Export Options
+
+| Option             | Type                                                      | Default | Description                                    |
+|--------------------|-----------------------------------------------------------|---------|------------------------------------------------|
+| `projectId`        | `string`                                                  | --      | GCP project ID                                 |
+| `datasetId`        | `string`                                                  | --      | BigQuery dataset ID                            |
+| `tableId`          | `string`                                                  | --      | BigQuery table ID                              |
+| `batchSize`        | `number`                                                  | `100`   | Events to buffer before inserting              |
+| `flushInterval`    | `number`                                                  | `5000`  | Interval (ms) to flush partial batches         |
+| `autoCreateTable`  | `boolean`                                                 | `false` | Create the table if it doesn't exist           |
+| `transform`        | `(event: Record<string, unknown>) => Record<string, unknown>` | --  | Transform each event row before insert         |
+
+Events are serialized as flat rows with `id`, `user_id`, `session_id`, `name`, `timestamp` (ISO 8601), and `payload` (JSON string). Use `transform` to reshape rows for your schema.
+
+## Import (Loading Datasets)
+
+```ts
+import { generate } from '@synode/core';
+import { BigQueryAdapter, importFromBigQuery } from '@synode/adapter-bigquery';
+
+const products = await importFromBigQuery({
+  projectId: 'my-project',
+  datasetId: 'ecommerce',
+  tableId: 'products',
+  id: 'products',
+  name: 'Products',
+  where: 'active = true',
+  limit: 1000,
+});
+
+await generate(journey, {
+  users: 100,
+  preloadedDatasets: [products],
+  adapter: new BigQueryAdapter({ ... }),
+});
+```
+
+### Import Options
+
+| Option      | Type     | Default     | Description                                    |
+|-------------|----------|-------------|------------------------------------------------|
+| `projectId` | `string` | --          | GCP project ID                                 |
+| `datasetId` | `string` | --          | BigQuery dataset ID                            |
+| `tableId`   | `string` | --          | BigQuery table ID to read from                 |
+| `where`     | `string` | --          | SQL WHERE clause to filter rows                |
+| `limit`     | `number` | unlimited   | Maximum number of rows to import               |
+| `id`        | `string` | --          | Synode dataset ID for the imported dataset      |
+| `name`      | `string` | --          | Synode dataset name                            |
+
+## Documentation
+
+- [Output Adapters Guide](https://synode-docs-1013393206713.europe-west1.run.app/guides/output-adapters)
+- [API Reference](https://synode-docs-1013393206713.europe-west1.run.app/api/types)
+- [GitHub](https://github.com/digitl-cloud/synode/tree/main/packages/adapter-bigquery)
+
+## License
+
+Proprietary -- see [LICENSE](https://github.com/digitl-cloud/synode/blob/main/LICENSE) for details.
+
+Copyright &copy; 2026 [Digitl Cloud GmbH](https://digitlcloud.com)

package/dist/index.cjs

@@ -0,0 +1,134 @@
+let __google_cloud_bigquery = require("@google-cloud/bigquery");
+
+//#region src/adapter.ts
+/**
+* BigQuery output adapter for Synode.
+*
+* Buffers generated events and inserts them into a BigQuery table in batches.
+* Events are serialized to flat rows with ISO timestamps and JSON-stringified payloads.
+*
+* @example
+* ```ts
+* const adapter = new BigQueryAdapter({
+*   projectId: 'my-project',
+*   datasetId: 'analytics',
+*   tableId: 'events',
+*   batchSize: 200,
+* });
+* await generate(journey, { users: 100, adapter });
+* await adapter.close();
+* ```
+*/
+var BigQueryAdapter = class {
+	client;
+	options;
+	buffer = [];
+	flushTimer = null;
+	constructor(options) {
+		this.client = new __google_cloud_bigquery.BigQuery({ projectId: options.projectId });
+		this.options = {
+			batchSize: 100,
+			flushInterval: 5e3,
+			...options
+		};
+	}
+	/**
+	* Buffers a single event for batch insertion.
+	* Triggers a flush when the buffer reaches {@link BigQueryAdapterOptions.batchSize}.
+	*
+	* @param event - The generated event to write
+	*/
+	async write(event) {
+		const row = this.serializeEvent(event);
+		const transformed = this.options.transform ? this.options.transform(row) : row;
+		this.buffer.push(transformed);
+		if (this.buffer.length >= this.options.batchSize) await this.flush();
+		else this.flushTimer ??= setTimeout(() => {
+			this.flush();
+		}, this.options.flushInterval);
+	}
+	/**
+	* Flushes any remaining buffered events and cleans up timers.
+	*/
+	async close() {
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = null;
+		}
+		if (this.buffer.length > 0) await this.flush();
+	}
+	/**
+	* Inserts all buffered rows into BigQuery and clears the buffer.
+	*/
+	async flush() {
+		if (this.buffer.length === 0) return;
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = null;
+		}
+		const rows = this.buffer.splice(0);
+		await this.client.dataset(this.options.datasetId).table(this.options.tableId).insert(rows);
+	}
+	/**
+	* Converts a synode Event into a flat BigQuery row.
+	*
+	* @param event - The event to serialize
+	* @returns A flat record with id, user_id, session_id, name, timestamp (ISO), and payload (JSON)
+	*/
+	serializeEvent(event) {
+		return {
+			id: event.id,
+			user_id: event.userId,
+			session_id: event.sessionId,
+			name: event.name,
+			timestamp: event.timestamp.toISOString(),
+			payload: JSON.stringify(event.payload)
+		};
+	}
+};
+
+//#endregion
+//#region src/import.ts
+/**
+* Import a BigQuery table as a synode Dataset.
+*
+* Queries the specified table and returns a Dataset object that can be
+* passed to `generate()` via the `preloadedDatasets` option.
+*
+* @param options - Import configuration including project, table, and synode dataset metadata
+* @returns A Dataset containing all matching rows from the BigQuery table
+*
+* @example
+* ```ts
+* const products = await importFromBigQuery({
+*   projectId: 'my-project',
+*   datasetId: 'ecommerce',
+*   tableId: 'products',
+*   id: 'products',
+*   name: 'Products',
+*   limit: 1000,
+* });
+*
+* await generate(journey, {
+*   users: 100,
+*   preloadedDatasets: [products],
+*   adapter,
+* });
+* ```
+*/
+async function importFromBigQuery(options) {
+	const client = new __google_cloud_bigquery.BigQuery({ projectId: options.projectId });
+	let query = `SELECT * FROM \`${options.projectId}.${options.datasetId}.${options.tableId}\``;
+	if (options.where) query += ` WHERE ${options.where}`;
+	if (options.limit) query += ` LIMIT ${String(options.limit)}`;
+	const [rows] = await client.query({ query });
+	return {
+		id: options.id,
+		name: options.name,
+		rows
+	};
+}
+
+//#endregion
+exports.BigQueryAdapter = BigQueryAdapter;
+exports.importFromBigQuery = importFromBigQuery;

package/dist/index.d.cts

@@ -0,0 +1,122 @@
+import { Dataset, Event, OutputAdapter } from "@synode/core";
+
+//#region src/types.d.ts
+/**
+ * Configuration for BigQuery event export.
+ */
+interface BigQueryAdapterOptions {
+  /** GCP project ID. */
+  projectId: string;
+  /** BigQuery dataset ID (not synode dataset -- BQ dataset). */
+  datasetId: string;
+  /** BigQuery table ID to write events to. */
+  tableId: string;
+  /** Number of events to batch before inserting. @default 100 */
+  batchSize?: number;
+  /** Maximum time (ms) to wait before flushing a partial batch. @default 5000 */
+  flushInterval?: number;
+  /** If true, create the table if it doesn't exist. @default false */
+  autoCreateTable?: boolean;
+  /** Optional transform function applied to each event before insert. */
+  transform?: (event: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Configuration for BigQuery dataset import.
+ */
+interface BigQueryImportOptions {
+  /** GCP project ID. */
+  projectId: string;
+  /** BigQuery dataset ID. */
+  datasetId: string;
+  /** BigQuery table ID to read from. */
+  tableId: string;
+  /** Optional SQL WHERE clause to filter rows. */
+  where?: string;
+  /** Maximum number of rows to import. @default unlimited */
+  limit?: number;
+  /** Synode dataset ID to assign to the imported dataset. */
+  id: string;
+  /** Synode dataset name. */
+  name: string;
+}
+//#endregion
+//#region src/adapter.d.ts
+/**
+ * BigQuery output adapter for Synode.
+ *
+ * Buffers generated events and inserts them into a BigQuery table in batches.
+ * Events are serialized to flat rows with ISO timestamps and JSON-stringified payloads.
+ *
+ * @example
+ * ```ts
+ * const adapter = new BigQueryAdapter({
+ *   projectId: 'my-project',
+ *   datasetId: 'analytics',
+ *   tableId: 'events',
+ *   batchSize: 200,
+ * });
+ * await generate(journey, { users: 100, adapter });
+ * await adapter.close();
+ * ```
+ */
+declare class BigQueryAdapter implements OutputAdapter {
+  private client;
+  private options;
+  private buffer;
+  private flushTimer;
+  constructor(options: BigQueryAdapterOptions);
+  /**
+   * Buffers a single event for batch insertion.
+   * Triggers a flush when the buffer reaches {@link BigQueryAdapterOptions.batchSize}.
+   *
+   * @param event - The generated event to write
+   */
+  write(event: Event): Promise<void>;
+  /**
+   * Flushes any remaining buffered events and cleans up timers.
+   */
+  close(): Promise<void>;
+  /**
+   * Inserts all buffered rows into BigQuery and clears the buffer.
+   */
+  private flush;
+  /**
+   * Converts a synode Event into a flat BigQuery row.
+   *
+   * @param event - The event to serialize
+   * @returns A flat record with id, user_id, session_id, name, timestamp (ISO), and payload (JSON)
+   */
+  private serializeEvent;
+}
+//#endregion
+//#region src/import.d.ts
+/**
+ * Import a BigQuery table as a synode Dataset.
+ *
+ * Queries the specified table and returns a Dataset object that can be
+ * passed to `generate()` via the `preloadedDatasets` option.
+ *
+ * @param options - Import configuration including project, table, and synode dataset metadata
+ * @returns A Dataset containing all matching rows from the BigQuery table
+ *
+ * @example
+ * ```ts
+ * const products = await importFromBigQuery({
+ *   projectId: 'my-project',
+ *   datasetId: 'ecommerce',
+ *   tableId: 'products',
+ *   id: 'products',
+ *   name: 'Products',
+ *   limit: 1000,
+ * });
+ *
+ * await generate(journey, {
+ *   users: 100,
+ *   preloadedDatasets: [products],
+ *   adapter,
+ * });
+ * ```
+ */
+declare function importFromBigQuery(options: BigQueryImportOptions): Promise<Dataset>;
+//#endregion
+export { BigQueryAdapter, type BigQueryAdapterOptions, type BigQueryImportOptions, importFromBigQuery };

package/dist/index.d.mts

@@ -0,0 +1,122 @@
+import { Dataset, Event, OutputAdapter } from "@synode/core";
+
+//#region src/types.d.ts
+/**
+ * Configuration for BigQuery event export.
+ */
+interface BigQueryAdapterOptions {
+  /** GCP project ID. */
+  projectId: string;
+  /** BigQuery dataset ID (not synode dataset -- BQ dataset). */
+  datasetId: string;
+  /** BigQuery table ID to write events to. */
+  tableId: string;
+  /** Number of events to batch before inserting. @default 100 */
+  batchSize?: number;
+  /** Maximum time (ms) to wait before flushing a partial batch. @default 5000 */
+  flushInterval?: number;
+  /** If true, create the table if it doesn't exist. @default false */
+  autoCreateTable?: boolean;
+  /** Optional transform function applied to each event before insert. */
+  transform?: (event: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Configuration for BigQuery dataset import.
+ */
+interface BigQueryImportOptions {
+  /** GCP project ID. */
+  projectId: string;
+  /** BigQuery dataset ID. */
+  datasetId: string;
+  /** BigQuery table ID to read from. */
+  tableId: string;
+  /** Optional SQL WHERE clause to filter rows. */
+  where?: string;
+  /** Maximum number of rows to import. @default unlimited */
+  limit?: number;
+  /** Synode dataset ID to assign to the imported dataset. */
+  id: string;
+  /** Synode dataset name. */
+  name: string;
+}
+//#endregion
+//#region src/adapter.d.ts
+/**
+ * BigQuery output adapter for Synode.
+ *
+ * Buffers generated events and inserts them into a BigQuery table in batches.
+ * Events are serialized to flat rows with ISO timestamps and JSON-stringified payloads.
+ *
+ * @example
+ * ```ts
+ * const adapter = new BigQueryAdapter({
+ *   projectId: 'my-project',
+ *   datasetId: 'analytics',
+ *   tableId: 'events',
+ *   batchSize: 200,
+ * });
+ * await generate(journey, { users: 100, adapter });
+ * await adapter.close();
+ * ```
+ */
+declare class BigQueryAdapter implements OutputAdapter {
+  private client;
+  private options;
+  private buffer;
+  private flushTimer;
+  constructor(options: BigQueryAdapterOptions);
+  /**
+   * Buffers a single event for batch insertion.
+   * Triggers a flush when the buffer reaches {@link BigQueryAdapterOptions.batchSize}.
+   *
+   * @param event - The generated event to write
+   */
+  write(event: Event): Promise<void>;
+  /**
+   * Flushes any remaining buffered events and cleans up timers.
+   */
+  close(): Promise<void>;
+  /**
+   * Inserts all buffered rows into BigQuery and clears the buffer.
+   */
+  private flush;
+  /**
+   * Converts a synode Event into a flat BigQuery row.
+   *
+   * @param event - The event to serialize
+   * @returns A flat record with id, user_id, session_id, name, timestamp (ISO), and payload (JSON)
+   */
+  private serializeEvent;
+}
+//#endregion
+//#region src/import.d.ts
+/**
+ * Import a BigQuery table as a synode Dataset.
+ *
+ * Queries the specified table and returns a Dataset object that can be
+ * passed to `generate()` via the `preloadedDatasets` option.
+ *
+ * @param options - Import configuration including project, table, and synode dataset metadata
+ * @returns A Dataset containing all matching rows from the BigQuery table
+ *
+ * @example
+ * ```ts
+ * const products = await importFromBigQuery({
+ *   projectId: 'my-project',
+ *   datasetId: 'ecommerce',
+ *   tableId: 'products',
+ *   id: 'products',
+ *   name: 'Products',
+ *   limit: 1000,
+ * });
+ *
+ * await generate(journey, {
+ *   users: 100,
+ *   preloadedDatasets: [products],
+ *   adapter,
+ * });
+ * ```
+ */
+declare function importFromBigQuery(options: BigQueryImportOptions): Promise<Dataset>;
+//#endregion
+export { BigQueryAdapter, type BigQueryAdapterOptions, type BigQueryImportOptions, importFromBigQuery };

package/dist/index.mjs

@@ -0,0 +1,133 @@
+import { BigQuery } from "@google-cloud/bigquery";
+
+//#region src/adapter.ts
+/**
+* BigQuery output adapter for Synode.
+*
+* Buffers generated events and inserts them into a BigQuery table in batches.
+* Events are serialized to flat rows with ISO timestamps and JSON-stringified payloads.
+*
+* @example
+* ```ts
+* const adapter = new BigQueryAdapter({
+*   projectId: 'my-project',
+*   datasetId: 'analytics',
+*   tableId: 'events',
+*   batchSize: 200,
+* });
+* await generate(journey, { users: 100, adapter });
+* await adapter.close();
+* ```
+*/
+var BigQueryAdapter = class {
+	client;
+	options;
+	buffer = [];
+	flushTimer = null;
+	constructor(options) {
+		this.client = new BigQuery({ projectId: options.projectId });
+		this.options = {
+			batchSize: 100,
+			flushInterval: 5e3,
+			...options
+		};
+	}
+	/**
+	* Buffers a single event for batch insertion.
+	* Triggers a flush when the buffer reaches {@link BigQueryAdapterOptions.batchSize}.
+	*
+	* @param event - The generated event to write
+	*/
+	async write(event) {
+		const row = this.serializeEvent(event);
+		const transformed = this.options.transform ? this.options.transform(row) : row;
+		this.buffer.push(transformed);
+		if (this.buffer.length >= this.options.batchSize) await this.flush();
+		else this.flushTimer ??= setTimeout(() => {
+			this.flush();
+		}, this.options.flushInterval);
+	}
+	/**
+	* Flushes any remaining buffered events and cleans up timers.
+	*/
+	async close() {
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = null;
+		}
+		if (this.buffer.length > 0) await this.flush();
+	}
+	/**
+	* Inserts all buffered rows into BigQuery and clears the buffer.
+	*/
+	async flush() {
+		if (this.buffer.length === 0) return;
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = null;
+		}
+		const rows = this.buffer.splice(0);
+		await this.client.dataset(this.options.datasetId).table(this.options.tableId).insert(rows);
+	}
+	/**
+	* Converts a synode Event into a flat BigQuery row.
+	*
+	* @param event - The event to serialize
+	* @returns A flat record with id, user_id, session_id, name, timestamp (ISO), and payload (JSON)
+	*/
+	serializeEvent(event) {
+		return {
+			id: event.id,
+			user_id: event.userId,
+			session_id: event.sessionId,
+			name: event.name,
+			timestamp: event.timestamp.toISOString(),
+			payload: JSON.stringify(event.payload)
+		};
+	}
+};
+
+//#endregion
+//#region src/import.ts
+/**
+* Import a BigQuery table as a synode Dataset.
+*
+* Queries the specified table and returns a Dataset object that can be
+* passed to `generate()` via the `preloadedDatasets` option.
+*
+* @param options - Import configuration including project, table, and synode dataset metadata
+* @returns A Dataset containing all matching rows from the BigQuery table
+*
+* @example
+* ```ts
+* const products = await importFromBigQuery({
+*   projectId: 'my-project',
+*   datasetId: 'ecommerce',
+*   tableId: 'products',
+*   id: 'products',
+*   name: 'Products',
+*   limit: 1000,
+* });
+*
+* await generate(journey, {
+*   users: 100,
+*   preloadedDatasets: [products],
+*   adapter,
+* });
+* ```
+*/
+async function importFromBigQuery(options) {
+	const client = new BigQuery({ projectId: options.projectId });
+	let query = `SELECT * FROM \`${options.projectId}.${options.datasetId}.${options.tableId}\``;
+	if (options.where) query += ` WHERE ${options.where}`;
+	if (options.limit) query += ` LIMIT ${String(options.limit)}`;
+	const [rows] = await client.query({ query });
+	return {
+		id: options.id,
+		name: options.name,
+		rows
+	};
+}
+
+//#endregion
+export { BigQueryAdapter, importFromBigQuery };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@synode/adapter-bigquery",
+  "version": "1.0.0",
+  "description": "BigQuery adapter for Synode — import datasets and export events",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "author": "Digitl Cloud GmbH",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/digitl-cloud/synode",
+    "directory": "packages/adapter-bigquery"
+  },
+  "peerDependencies": {
+    "@synode/core": "^1.0.0",
+    "@google-cloud/bigquery": "^7.0.0 || ^8.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@google-cloud/bigquery": "^8.1.1",
+    "@types/node": "^24.12.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "tsdown": "^0.16.8",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^4.1.2",
+    "@synode/core": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "lint": "eslint src tests"
+  }
+}