@synode/adapter-file 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/dist/index.cjs

@@ -0,0 +1,166 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let node_fs_promises = require("node:fs/promises");
+node_fs_promises = __toESM(node_fs_promises);
+let node_path = require("node:path");
+node_path = __toESM(node_path);
+let __synode_core = require("@synode/core");
+
+//#region src/index.ts
+const FORMAT_EXTENSION = {
+	jsonl: "jsonl",
+	json: "json",
+	csv: "csv"
+};
+/**
+* Adapter that writes events to the local filesystem.
+*
+* Supports JSONL (append per event), JSON (buffered array), and CSV formats
+* with optional daily partitioning by event timestamp.
+*
+* @example
+* ```ts
+* const adapter = new FileAdapter({ path: './out/events.jsonl', format: 'jsonl' });
+* await generate(journey, { users: 10, adapter });
+* await adapter.close();
+* ```
+*
+* @example
+* ```ts
+* // Daily-partitioned CSV output
+* const adapter = new FileAdapter({
+*   path: './out',
+*   format: 'csv',
+*   partition: 'daily',
+*   filePattern: 'events-{date}.{ext}',
+* });
+* ```
+*/
+var FileAdapter = class {
+	options;
+	jsonBuffer = [];
+	csvHeadersWritten = /* @__PURE__ */ new Set();
+	csvHeaders = null;
+	constructor(options) {
+		this.options = {
+			partition: "none",
+			filePattern: "events-{date}.{ext}",
+			...options
+		};
+	}
+	/** @inheritdoc */
+	async write(event) {
+		const filePath = this.resolveFilePath(event);
+		await this.ensureDirectory(filePath);
+		switch (this.options.format) {
+			case "jsonl":
+				await this.writeJsonl(filePath, event);
+				break;
+			case "json":
+				this.jsonBuffer.push(event);
+				break;
+			case "csv":
+				await this.writeCsv(filePath, event);
+				break;
+		}
+	}
+	/** @inheritdoc */
+	async close() {
+		if (this.options.format !== "json") return;
+		if (this.options.partition === "daily") {
+			const grouped = this.groupByDate(this.jsonBuffer);
+			for (const [date, events] of grouped) {
+				const filePath = this.buildPartitionedPath(date);
+				await this.ensureDirectory(filePath);
+				await node_fs_promises.writeFile(filePath, JSON.stringify(events, null, 2), "utf-8");
+			}
+		} else {
+			const filePath = this.safePath(this.options.path);
+			await this.ensureDirectory(filePath);
+			await node_fs_promises.writeFile(filePath, JSON.stringify(this.jsonBuffer, null, 2), "utf-8");
+		}
+	}
+	resolveFilePath(event) {
+		if (this.options.partition === "daily") {
+			const date = this.formatDate(event.timestamp);
+			return this.buildPartitionedPath(date);
+		}
+		return this.safePath(this.options.path);
+	}
+	buildPartitionedPath(date) {
+		const ext = FORMAT_EXTENSION[this.options.format];
+		return (0, __synode_core.validateFilePath)(this.options.filePattern.replace("{date}", date).replace("{ext}", ext), node_path.resolve(this.options.path));
+	}
+	/**
+	* Resolves and validates a file path against its own parent directory.
+	* This prevents path traversal (e.g., `../../etc/passwd`) while allowing
+	* absolute paths outside the current working directory.
+	*/
+	safePath(filePath) {
+		const resolved = node_path.resolve(filePath);
+		return (0, __synode_core.validateFilePath)(resolved, node_path.dirname(resolved));
+	}
+	async ensureDirectory(filePath) {
+		await node_fs_promises.mkdir(node_path.dirname(filePath), { recursive: true });
+	}
+	async writeJsonl(filePath, event) {
+		await node_fs_promises.appendFile(filePath, JSON.stringify(event) + "\n", "utf-8");
+	}
+	async writeCsv(filePath, event) {
+		this.csvHeaders ??= Object.keys(event.payload);
+		if (!this.csvHeadersWritten.has(filePath)) {
+			await node_fs_promises.appendFile(filePath, this.csvHeaders.join(",") + "\n", "utf-8");
+			this.csvHeadersWritten.add(filePath);
+		}
+		const row = this.csvHeaders.map((header) => this.escapeCSVValue(event.payload[header]));
+		await node_fs_promises.appendFile(filePath, row.join(",") + "\n", "utf-8");
+	}
+	escapeCSVValue(value) {
+		if (value == null) return "";
+		const str = typeof value === "string" ? value : typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" ? value.toString() : JSON.stringify(value);
+		if (str.includes(",") || str.includes("\"") || str.includes("\n")) return "\"" + str.replace(/"/g, "\"\"") + "\"";
+		return str;
+	}
+	formatDate(date) {
+		return `${String(date.getUTCFullYear())}-${String(date.getUTCMonth() + 1).padStart(2, "0")}-${String(date.getUTCDate()).padStart(2, "0")}`;
+	}
+	groupByDate(events) {
+		const grouped = /* @__PURE__ */ new Map();
+		for (const event of events) {
+			const date = this.formatDate(event.timestamp);
+			const existing = grouped.get(date);
+			if (existing) existing.push(event);
+			else grouped.set(date, [event]);
+		}
+		return grouped;
+	}
+};
+
+//#endregion
+exports.FileAdapter = FileAdapter;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["FORMAT_EXTENSION: Record<FileAdapterOptions['format'], string>","fs","path"],"sources":["../src/index.ts"],"sourcesContent":["import * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport type { Event, OutputAdapter } from '@synode/core';\nimport { validateFilePath } from '@synode/core';\n\n/**\n * Configuration options for {@link FileAdapter}.\n *\n * @param path - Output file path (used directly when partition is 'none')\n * @param format - Serialization format: 'jsonl' (one JSON object per line),\n *   'json' (single JSON array), or 'csv' (header + rows)\n * @param partition - Partitioning strategy. 'daily' creates separate files\n *   based on each event's timestamp date. Defaults to 'none'.\n * @param filePattern - Template for partitioned file names. Supports `{date}`\n *   (replaced with YYYY-MM-DD) and `{ext}` (replaced with the format extension).\n *   Defaults to `'events-{date}.{ext}'`.\n */\nexport interface FileAdapterOptions {\n  path: string;\n  format: 'jsonl' | 'json' | 'csv';\n  partition?: 'daily' | 'none';\n  filePattern?: string;\n}\n\nconst FORMAT_EXTENSION: Record<FileAdapterOptions['format'], string> = {\n  jsonl: 'jsonl',\n  json: 'json',\n  csv: 'csv',\n};\n\n/**\n * Adapter that writes events to the local filesystem.\n *\n * Supports JSONL (append per event), JSON (buffered array), and CSV formats\n * with optional daily partitioning by event timestamp.\n *\n * @example\n * ```ts\n * const adapter = new FileAdapter({ path: './out/events.jsonl', format: 'jsonl' });\n * await generate(journey, { users: 10, adapter });\n * await adapter.close();\n * ```\n *\n * @example\n * ```ts\n * // Daily-partitioned CSV output\n * const adapter = new FileAdapter({\n *   path: './out',\n *   format: 'csv',\n *   partition: 'daily',\n *   filePattern: 'events-{date}.{ext}',\n * });\n * ```\n */\nexport class FileAdapter implements OutputAdapter {\n  private readonly options: Required<FileAdapterOptions>;\n  private readonly jsonBuffer: Event[] = [];\n  private readonly csvHeadersWritten = new Set<string>();\n  private csvHeaders: string[] | null = null;\n\n  constructor(options: FileAdapterOptions) {\n    this.options = {\n      partition: 'none',\n      filePattern: 'events-{date}.{ext}',\n      ...options,\n    };\n  }\n\n  /** @inheritdoc */\n  async write(event: Event): Promise<void> {\n    const filePath = this.resolveFilePath(event);\n    await this.ensureDirectory(filePath);\n\n    switch (this.options.format) {\n      case 'jsonl':\n        await this.writeJsonl(filePath, event);\n        break;\n      case 'json':\n        this.jsonBuffer.push(event);\n        break;\n      case 'csv':\n        await this.writeCsv(filePath, event);\n        break;\n    }\n  }\n\n  /** @inheritdoc */\n  async close(): Promise<void> {\n    if (this.options.format !== 'json') {\n      return;\n    }\n\n    if (this.options.partition === 'daily') {\n      const grouped = this.groupByDate(this.jsonBuffer);\n      for (const [date, events] of grouped) {\n        const filePath = this.buildPartitionedPath(date);\n        await this.ensureDirectory(filePath);\n        await fs.writeFile(filePath, JSON.stringify(events, null, 2), 'utf-8');\n      }\n    } else {\n      const filePath = this.safePath(this.options.path);\n      await this.ensureDirectory(filePath);\n      await fs.writeFile(filePath, JSON.stringify(this.jsonBuffer, null, 2), 'utf-8');\n    }\n  }\n\n  private resolveFilePath(event: Event): string {\n    if (this.options.partition === 'daily') {\n      const date = this.formatDate(event.timestamp);\n      return this.buildPartitionedPath(date);\n    }\n    return this.safePath(this.options.path);\n  }\n\n  private buildPartitionedPath(date: string): string {\n    const ext = FORMAT_EXTENSION[this.options.format];\n    const fileName = this.options.filePattern.replace('{date}', date).replace('{ext}', ext);\n    const baseDir = path.resolve(this.options.path);\n    return validateFilePath(fileName, baseDir);\n  }\n\n  /**\n   * Resolves and validates a file path against its own parent directory.\n   * This prevents path traversal (e.g., `../../etc/passwd`) while allowing\n   * absolute paths outside the current working directory.\n   */\n  private safePath(filePath: string): string {\n    const resolved = path.resolve(filePath);\n    const parentDir = path.dirname(resolved);\n    return validateFilePath(resolved, parentDir);\n  }\n\n  private async ensureDirectory(filePath: string): Promise<void> {\n    await fs.mkdir(path.dirname(filePath), { recursive: true });\n  }\n\n  private async writeJsonl(filePath: string, event: Event): Promise<void> {\n    await fs.appendFile(filePath, JSON.stringify(event) + '\\n', 'utf-8');\n  }\n\n  private async writeCsv(filePath: string, event: Event): Promise<void> {\n    this.csvHeaders ??= Object.keys(event.payload);\n\n    if (!this.csvHeadersWritten.has(filePath)) {\n      await fs.appendFile(filePath, this.csvHeaders.join(',') + '\\n', 'utf-8');\n      this.csvHeadersWritten.add(filePath);\n    }\n\n    const row = this.csvHeaders.map((header) => this.escapeCSVValue(event.payload[header]));\n    await fs.appendFile(filePath, row.join(',') + '\\n', 'utf-8');\n  }\n\n  private escapeCSVValue(value: unknown): string {\n    if (value == null) {\n      return '';\n    }\n    const str =\n      typeof value === 'string'\n        ? value\n        : typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint'\n          ? value.toString()\n          : JSON.stringify(value);\n    if (str.includes(',') || str.includes('\"') || str.includes('\\n')) {\n      return '\"' + str.replace(/\"/g, '\"\"') + '\"';\n    }\n    return str;\n  }\n\n  private formatDate(date: Date): string {\n    const year = String(date.getUTCFullYear());\n    const month = String(date.getUTCMonth() + 1).padStart(2, '0');\n    const day = String(date.getUTCDate()).padStart(2, '0');\n    return `${year}-${month}-${day}`;\n  }\n\n  private groupByDate(events: Event[]): Map<string, Event[]> {\n    const grouped = new Map<string, Event[]>();\n    for (const event of events) {\n      const date = this.formatDate(event.timestamp);\n      const existing = grouped.get(date);\n      if (existing) {\n        existing.push(event);\n      } else {\n        grouped.set(date, [event]);\n      }\n    }\n    return grouped;\n  }\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,74 @@
+import { Event, OutputAdapter } from "@synode/core";
+
+//#region src/index.d.ts
+
+/**
+ * Configuration options for {@link FileAdapter}.
+ *
+ * @param path - Output file path (used directly when partition is 'none')
+ * @param format - Serialization format: 'jsonl' (one JSON object per line),
+ *   'json' (single JSON array), or 'csv' (header + rows)
+ * @param partition - Partitioning strategy. 'daily' creates separate files
+ *   based on each event's timestamp date. Defaults to 'none'.
+ * @param filePattern - Template for partitioned file names. Supports `{date}`
+ *   (replaced with YYYY-MM-DD) and `{ext}` (replaced with the format extension).
+ *   Defaults to `'events-{date}.{ext}'`.
+ */
+interface FileAdapterOptions {
+  path: string;
+  format: 'jsonl' | 'json' | 'csv';
+  partition?: 'daily' | 'none';
+  filePattern?: string;
+}
+/**
+ * Adapter that writes events to the local filesystem.
+ *
+ * Supports JSONL (append per event), JSON (buffered array), and CSV formats
+ * with optional daily partitioning by event timestamp.
+ *
+ * @example
+ * ```ts
+ * const adapter = new FileAdapter({ path: './out/events.jsonl', format: 'jsonl' });
+ * await generate(journey, { users: 10, adapter });
+ * await adapter.close();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Daily-partitioned CSV output
+ * const adapter = new FileAdapter({
+ *   path: './out',
+ *   format: 'csv',
+ *   partition: 'daily',
+ *   filePattern: 'events-{date}.{ext}',
+ * });
+ * ```
+ */
+declare class FileAdapter implements OutputAdapter {
+  private readonly options;
+  private readonly jsonBuffer;
+  private readonly csvHeadersWritten;
+  private csvHeaders;
+  constructor(options: FileAdapterOptions);
+  /** @inheritdoc */
+  write(event: Event): Promise<void>;
+  /** @inheritdoc */
+  close(): Promise<void>;
+  private resolveFilePath;
+  private buildPartitionedPath;
+  /**
+   * Resolves and validates a file path against its own parent directory.
+   * This prevents path traversal (e.g., `../../etc/passwd`) while allowing
+   * absolute paths outside the current working directory.
+   */
+  private safePath;
+  private ensureDirectory;
+  private writeJsonl;
+  private writeCsv;
+  private escapeCSVValue;
+  private formatDate;
+  private groupByDate;
+}
+//#endregion
+export { FileAdapter, FileAdapterOptions };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+import { Event, OutputAdapter } from "@synode/core";
+
+//#region src/index.d.ts
+
+/**
+ * Configuration options for {@link FileAdapter}.
+ *
+ * @param path - Output file path (used directly when partition is 'none')
+ * @param format - Serialization format: 'jsonl' (one JSON object per line),
+ *   'json' (single JSON array), or 'csv' (header + rows)
+ * @param partition - Partitioning strategy. 'daily' creates separate files
+ *   based on each event's timestamp date. Defaults to 'none'.
+ * @param filePattern - Template for partitioned file names. Supports `{date}`
+ *   (replaced with YYYY-MM-DD) and `{ext}` (replaced with the format extension).
+ *   Defaults to `'events-{date}.{ext}'`.
+ */
+interface FileAdapterOptions {
+  path: string;
+  format: 'jsonl' | 'json' | 'csv';
+  partition?: 'daily' | 'none';
+  filePattern?: string;
+}
+/**
+ * Adapter that writes events to the local filesystem.
+ *
+ * Supports JSONL (append per event), JSON (buffered array), and CSV formats
+ * with optional daily partitioning by event timestamp.
+ *
+ * @example
+ * ```ts
+ * const adapter = new FileAdapter({ path: './out/events.jsonl', format: 'jsonl' });
+ * await generate(journey, { users: 10, adapter });
+ * await adapter.close();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Daily-partitioned CSV output
+ * const adapter = new FileAdapter({
+ *   path: './out',
+ *   format: 'csv',
+ *   partition: 'daily',
+ *   filePattern: 'events-{date}.{ext}',
+ * });
+ * ```
+ */
+declare class FileAdapter implements OutputAdapter {
+  private readonly options;
+  private readonly jsonBuffer;
+  private readonly csvHeadersWritten;
+  private csvHeaders;
+  constructor(options: FileAdapterOptions);
+  /** @inheritdoc */
+  write(event: Event): Promise<void>;
+  /** @inheritdoc */
+  close(): Promise<void>;
+  private resolveFilePath;
+  private buildPartitionedPath;
+  /**
+   * Resolves and validates a file path against its own parent directory.
+   * This prevents path traversal (e.g., `../../etc/passwd`) while allowing
+   * absolute paths outside the current working directory.
+   */
+  private safePath;
+  private ensureDirectory;
+  private writeJsonl;
+  private writeCsv;
+  private escapeCSVValue;
+  private formatDate;
+  private groupByDate;
+}
+//#endregion
+export { FileAdapter, FileAdapterOptions };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,137 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { validateFilePath } from "@synode/core";
+
+//#region src/index.ts
+const FORMAT_EXTENSION = {
+	jsonl: "jsonl",
+	json: "json",
+	csv: "csv"
+};
+/**
+* Adapter that writes events to the local filesystem.
+*
+* Supports JSONL (append per event), JSON (buffered array), and CSV formats
+* with optional daily partitioning by event timestamp.
+*
+* @example
+* ```ts
+* const adapter = new FileAdapter({ path: './out/events.jsonl', format: 'jsonl' });
+* await generate(journey, { users: 10, adapter });
+* await adapter.close();
+* ```
+*
+* @example
+* ```ts
+* // Daily-partitioned CSV output
+* const adapter = new FileAdapter({
+*   path: './out',
+*   format: 'csv',
+*   partition: 'daily',
+*   filePattern: 'events-{date}.{ext}',
+* });
+* ```
+*/
+var FileAdapter = class {
+	options;
+	jsonBuffer = [];
+	csvHeadersWritten = /* @__PURE__ */ new Set();
+	csvHeaders = null;
+	constructor(options) {
+		this.options = {
+			partition: "none",
+			filePattern: "events-{date}.{ext}",
+			...options
+		};
+	}
+	/** @inheritdoc */
+	async write(event) {
+		const filePath = this.resolveFilePath(event);
+		await this.ensureDirectory(filePath);
+		switch (this.options.format) {
+			case "jsonl":
+				await this.writeJsonl(filePath, event);
+				break;
+			case "json":
+				this.jsonBuffer.push(event);
+				break;
+			case "csv":
+				await this.writeCsv(filePath, event);
+				break;
+		}
+	}
+	/** @inheritdoc */
+	async close() {
+		if (this.options.format !== "json") return;
+		if (this.options.partition === "daily") {
+			const grouped = this.groupByDate(this.jsonBuffer);
+			for (const [date, events] of grouped) {
+				const filePath = this.buildPartitionedPath(date);
+				await this.ensureDirectory(filePath);
+				await fs.writeFile(filePath, JSON.stringify(events, null, 2), "utf-8");
+			}
+		} else {
+			const filePath = this.safePath(this.options.path);
+			await this.ensureDirectory(filePath);
+			await fs.writeFile(filePath, JSON.stringify(this.jsonBuffer, null, 2), "utf-8");
+		}
+	}
+	resolveFilePath(event) {
+		if (this.options.partition === "daily") {
+			const date = this.formatDate(event.timestamp);
+			return this.buildPartitionedPath(date);
+		}
+		return this.safePath(this.options.path);
+	}
+	buildPartitionedPath(date) {
+		const ext = FORMAT_EXTENSION[this.options.format];
+		return validateFilePath(this.options.filePattern.replace("{date}", date).replace("{ext}", ext), path.resolve(this.options.path));
+	}
+	/**
+	* Resolves and validates a file path against its own parent directory.
+	* This prevents path traversal (e.g., `../../etc/passwd`) while allowing
+	* absolute paths outside the current working directory.
+	*/
+	safePath(filePath) {
+		const resolved = path.resolve(filePath);
+		return validateFilePath(resolved, path.dirname(resolved));
+	}
+	async ensureDirectory(filePath) {
+		await fs.mkdir(path.dirname(filePath), { recursive: true });
+	}
+	async writeJsonl(filePath, event) {
+		await fs.appendFile(filePath, JSON.stringify(event) + "\n", "utf-8");
+	}
+	async writeCsv(filePath, event) {
+		this.csvHeaders ??= Object.keys(event.payload);
+		if (!this.csvHeadersWritten.has(filePath)) {
+			await fs.appendFile(filePath, this.csvHeaders.join(",") + "\n", "utf-8");
+			this.csvHeadersWritten.add(filePath);
+		}
+		const row = this.csvHeaders.map((header) => this.escapeCSVValue(event.payload[header]));
+		await fs.appendFile(filePath, row.join(",") + "\n", "utf-8");
+	}
+	escapeCSVValue(value) {
+		if (value == null) return "";
+		const str = typeof value === "string" ? value : typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" ? value.toString() : JSON.stringify(value);
+		if (str.includes(",") || str.includes("\"") || str.includes("\n")) return "\"" + str.replace(/"/g, "\"\"") + "\"";
+		return str;
+	}
+	formatDate(date) {
+		return `${String(date.getUTCFullYear())}-${String(date.getUTCMonth() + 1).padStart(2, "0")}-${String(date.getUTCDate()).padStart(2, "0")}`;
+	}
+	groupByDate(events) {
+		const grouped = /* @__PURE__ */ new Map();
+		for (const event of events) {
+			const date = this.formatDate(event.timestamp);
+			const existing = grouped.get(date);
+			if (existing) existing.push(event);
+			else grouped.set(date, [event]);
+		}
+		return grouped;
+	}
+};
+
+//#endregion
+export { FileAdapter };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["FORMAT_EXTENSION: Record<FileAdapterOptions['format'], string>"],"sources":["../src/index.ts"],"sourcesContent":["import * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport type { Event, OutputAdapter } from '@synode/core';\nimport { validateFilePath } from '@synode/core';\n\n/**\n * Configuration options for {@link FileAdapter}.\n *\n * @param path - Output file path (used directly when partition is 'none')\n * @param format - Serialization format: 'jsonl' (one JSON object per line),\n *   'json' (single JSON array), or 'csv' (header + rows)\n * @param partition - Partitioning strategy. 'daily' creates separate files\n *   based on each event's timestamp date. Defaults to 'none'.\n * @param filePattern - Template for partitioned file names. Supports `{date}`\n *   (replaced with YYYY-MM-DD) and `{ext}` (replaced with the format extension).\n *   Defaults to `'events-{date}.{ext}'`.\n */\nexport interface FileAdapterOptions {\n  path: string;\n  format: 'jsonl' | 'json' | 'csv';\n  partition?: 'daily' | 'none';\n  filePattern?: string;\n}\n\nconst FORMAT_EXTENSION: Record<FileAdapterOptions['format'], string> = {\n  jsonl: 'jsonl',\n  json: 'json',\n  csv: 'csv',\n};\n\n/**\n * Adapter that writes events to the local filesystem.\n *\n * Supports JSONL (append per event), JSON (buffered array), and CSV formats\n * with optional daily partitioning by event timestamp.\n *\n * @example\n * ```ts\n * const adapter = new FileAdapter({ path: './out/events.jsonl', format: 'jsonl' });\n * await generate(journey, { users: 10, adapter });\n * await adapter.close();\n * ```\n *\n * @example\n * ```ts\n * // Daily-partitioned CSV output\n * const adapter = new FileAdapter({\n *   path: './out',\n *   format: 'csv',\n *   partition: 'daily',\n *   filePattern: 'events-{date}.{ext}',\n * });\n * ```\n */\nexport class FileAdapter implements OutputAdapter {\n  private readonly options: Required<FileAdapterOptions>;\n  private readonly jsonBuffer: Event[] = [];\n  private readonly csvHeadersWritten = new Set<string>();\n  private csvHeaders: string[] | null = null;\n\n  constructor(options: FileAdapterOptions) {\n    this.options = {\n      partition: 'none',\n      filePattern: 'events-{date}.{ext}',\n      ...options,\n    };\n  }\n\n  /** @inheritdoc */\n  async write(event: Event): Promise<void> {\n    const filePath = this.resolveFilePath(event);\n    await this.ensureDirectory(filePath);\n\n    switch (this.options.format) {\n      case 'jsonl':\n        await this.writeJsonl(filePath, event);\n        break;\n      case 'json':\n        this.jsonBuffer.push(event);\n        break;\n      case 'csv':\n        await this.writeCsv(filePath, event);\n        break;\n    }\n  }\n\n  /** @inheritdoc */\n  async close(): Promise<void> {\n    if (this.options.format !== 'json') {\n      return;\n    }\n\n    if (this.options.partition === 'daily') {\n      const grouped = this.groupByDate(this.jsonBuffer);\n      for (const [date, events] of grouped) {\n        const filePath = this.buildPartitionedPath(date);\n        await this.ensureDirectory(filePath);\n        await fs.writeFile(filePath, JSON.stringify(events, null, 2), 'utf-8');\n      }\n    } else {\n      const filePath = this.safePath(this.options.path);\n      await this.ensureDirectory(filePath);\n      await fs.writeFile(filePath, JSON.stringify(this.jsonBuffer, null, 2), 'utf-8');\n    }\n  }\n\n  private resolveFilePath(event: Event): string {\n    if (this.options.partition === 'daily') {\n      const date = this.formatDate(event.timestamp);\n      return this.buildPartitionedPath(date);\n    }\n    return this.safePath(this.options.path);\n  }\n\n  private buildPartitionedPath(date: string): string {\n    const ext = FORMAT_EXTENSION[this.options.format];\n    const fileName = this.options.filePattern.replace('{date}', date).replace('{ext}', ext);\n    const baseDir = path.resolve(this.options.path);\n    return validateFilePath(fileName, baseDir);\n  }\n\n  /**\n   * Resolves and validates a file path against its own parent directory.\n   * This prevents path traversal (e.g., `../../etc/passwd`) while allowing\n   * absolute paths outside the current working directory.\n   */\n  private safePath(filePath: string): string {\n    const resolved = path.resolve(filePath);\n    const parentDir = path.dirname(resolved);\n    return validateFilePath(resolved, parentDir);\n  }\n\n  private async ensureDirectory(filePath: string): Promise<void> {\n    await fs.mkdir(path.dirname(filePath), { recursive: true });\n  }\n\n  private async writeJsonl(filePath: string, event: Event): Promise<void> {\n    await fs.appendFile(filePath, JSON.stringify(event) + '\\n', 'utf-8');\n  }\n\n  private async writeCsv(filePath: string, event: Event): Promise<void> {\n    this.csvHeaders ??= Object.keys(event.payload);\n\n    if (!this.csvHeadersWritten.has(filePath)) {\n      await fs.appendFile(filePath, this.csvHeaders.join(',') + '\\n', 'utf-8');\n      this.csvHeadersWritten.add(filePath);\n    }\n\n    const row = this.csvHeaders.map((header) => this.escapeCSVValue(event.payload[header]));\n    await fs.appendFile(filePath, row.join(',') + '\\n', 'utf-8');\n  }\n\n  private escapeCSVValue(value: unknown): string {\n    if (value == null) {\n      return '';\n    }\n    const str =\n      typeof value === 'string'\n        ? value\n        : typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint'\n          ? value.toString()\n          : JSON.stringify(value);\n    if (str.includes(',') || str.includes('\"') || str.includes('\\n')) {\n      return '\"' + str.replace(/\"/g, '\"\"') + '\"';\n    }\n    return str;\n  }\n\n  private formatDate(date: Date): string {\n    const year = String(date.getUTCFullYear());\n    const month = String(date.getUTCMonth() + 1).padStart(2, '0');\n    const day = String(date.getUTCDate()).padStart(2, '0');\n    return `${year}-${month}-${day}`;\n  }\n\n  private groupByDate(events: Event[]): Map<string, Event[]> {\n    const grouped = new Map<string, Event[]>();\n    for (const event of events) {\n      const date = this.formatDate(event.timestamp);\n      const existing = grouped.get(date);\n      if (existing) {\n        existing.push(event);\n      } else {\n        grouped.set(date, [event]);\n      }\n    }\n    return grouped;\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@synode/adapter-file",
+  "version": "1.0.0",
+  "description": "File adapter for Synode",
+  "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-file"
+  },
+  "peerDependencies": {
+    "@synode/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "typescript-eslint": "^8.58.0",
+    "tsdown": "^0.16.8",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2",
+    "@synode/core": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "lint": "eslint src tests"
+  }
+}