@walkeros/server-destination-file 3.4.0-next-1776749829492

package/dist/examples/index.d.ts

@@ -0,0 +1,113 @@
+import { DestinationServer } from '@walkeros/server-core';
+import { WriteStream } from 'node:fs';
+import { Flow } from '@walkeros/core';
+
+type Format = 'jsonl' | 'tsv' | 'csv';
+/**
+ * Minimal write-stream interface used by the destination. Matches the
+ * subset of node:fs WriteStream needed for append-only writes. Tests
+ * inject a fake implementation via env.fs.
+ */
+interface FileWriteStream {
+    write: (chunk: string) => boolean;
+    end: () => void;
+}
+interface Env extends DestinationServer.Env {
+    /**
+     * Override the file system primitives. Tests inject a fake here so
+     * disk writes are captured in memory.
+     */
+    fs?: {
+        createWriteStream: (path: string, options: {
+            flags: string;
+        }) => FileWriteStream | WriteStream;
+        mkdir: (path: string, options: {
+            recursive: boolean;
+        }) => Promise<void>;
+    };
+}
+
+/**
+ * Captured file state for assertions in tests.
+ */
+interface CapturedFile {
+    filename: string;
+    lines: string[];
+    ended: boolean;
+}
+interface SpyState {
+    captured: Map<string, CapturedFile>;
+    mkdirCalls: string[];
+}
+interface SpyEnv extends Env {
+    _spy: SpyState;
+}
+declare const init: SpyEnv;
+declare const push: SpyEnv;
+
+type env_CapturedFile = CapturedFile;
+type env_SpyEnv = SpyEnv;
+type env_SpyState = SpyState;
+declare const env_init: typeof init;
+declare const env_push: typeof push;
+declare namespace env {
+  export { type env_CapturedFile as CapturedFile, type env_SpyEnv as SpyEnv, type env_SpyState as SpyState, env_init as init, env_push as push };
+}
+
+/**
+ * Raw filename-config shape accepted in step examples and flow.json.
+ * Mirrors the runtime Settings.filename but types `fn` as string so
+ * `$code:` tags (resolved at bundle time by walkerOS) are expressible
+ * here without casting to a function type.
+ */
+interface FileSettingsJson {
+    filename: string | {
+        key?: string;
+        fn?: string | ((value: unknown) => unknown);
+        value?: unknown;
+    };
+    format?: Format;
+    fields?: string[];
+}
+/**
+ * Extended step example that carries destination-level settings for the
+ * file destination.
+ *
+ * `out` is modeled at intent level as a single `['fs.writeFile', path, line]`
+ * tuple per event (even though the destination internally uses a persistent
+ * createWriteStream + write). This matches the design doc's preference for
+ * readable intent-level callable tuples over stream-chain fidelity.
+ *
+ * Dropped / ignored events produce `out: []`.
+ */
+type FileStepExample = Flow.StepExample & {
+    settings: FileSettingsJson;
+};
+/** Default JSONL append. Static filename, all defaults. */
+declare const jsonlDefault: FileStepExample;
+/** Baersch-style TSV log: PHP parity case. */
+declare const tsvBaerschLog: FileStepExample;
+/** Tenant sharding via plain key extraction. */
+declare const jsonlTenantShardKey: FileStepExample;
+/**
+ * Daily rotation via a mapping fn. In flow.json this is authored as a
+ * `$code:` string; walkerOS compiles it to a function at bundle time. For
+ * in-process tests we pass the already-compiled function directly so the
+ * example exercises the same code path without needing the bundler.
+ */
+declare const jsonlDailyRotation: FileStepExample;
+/** CSV with an object cell. data is JSON-stringified, properly quoted. */
+declare const csvObjectCell: FileStepExample;
+
+type step_FileSettingsJson = FileSettingsJson;
+type step_FileStepExample = FileStepExample;
+declare const step_csvObjectCell: typeof csvObjectCell;
+declare const step_jsonlDailyRotation: typeof jsonlDailyRotation;
+declare const step_jsonlDefault: typeof jsonlDefault;
+declare const step_jsonlTenantShardKey: typeof jsonlTenantShardKey;
+declare const step_tsvBaerschLog: typeof tsvBaerschLog;
+declare namespace step {
+  export { type step_FileSettingsJson as FileSettingsJson, type step_FileStepExample as FileStepExample, step_csvObjectCell as csvObjectCell, step_jsonlDailyRotation as jsonlDailyRotation, step_jsonlDefault as jsonlDefault, step_jsonlTenantShardKey as jsonlTenantShardKey, step_tsvBaerschLog as tsvBaerschLog };
+}
+
+export { env, step };

package/dist/examples/index.js

@@ -0,0 +1,178 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/examples/index.ts
+var examples_exports = {};
+__export(examples_exports, {
+  env: () => env_exports,
+  step: () => step_exports
+});
+module.exports = __toCommonJS(examples_exports);
+
+// src/examples/env.ts
+var env_exports = {};
+__export(env_exports, {
+  init: () => init,
+  push: () => push
+});
+function makeSpyEnv() {
+  const state = {
+    captured: /* @__PURE__ */ new Map(),
+    mkdirCalls: []
+  };
+  const createWriteStream = (path) => {
+    const existing = state.captured.get(path);
+    const file = existing != null ? existing : {
+      filename: path,
+      lines: [],
+      ended: false
+    };
+    if (!existing) state.captured.set(path, file);
+    const stream = {
+      write(chunk) {
+        file.lines.push(chunk);
+        return true;
+      },
+      end() {
+        file.ended = true;
+      }
+    };
+    return stream;
+  };
+  const mkdir = async (path) => {
+    state.mkdirCalls.push(path);
+  };
+  return {
+    _spy: state,
+    fs: {
+      createWriteStream,
+      mkdir
+    }
+  };
+}
+var init = makeSpyEnv();
+var push = makeSpyEnv();
+
+// src/examples/step.ts
+var step_exports = {};
+__export(step_exports, {
+  csvObjectCell: () => csvObjectCell,
+  jsonlDailyRotation: () => jsonlDailyRotation,
+  jsonlDefault: () => jsonlDefault,
+  jsonlTenantShardKey: () => jsonlTenantShardKey,
+  tsvBaerschLog: () => tsvBaerschLog
+});
+var import_core = require("@walkeros/core");
+var jsonlDefault = {
+  in: (0, import_core.getEvent)("page view", { timestamp: 17e11 }),
+  settings: { filename: "events.jsonl" },
+  out: [
+    [
+      "fs.writeFile",
+      "events.jsonl",
+      // JSONL framework contract: JSON.stringify(event) + '\n'.
+      // The test recomputes this from example.in for the jsonl default to
+      // avoid duplicating the full event shape here.
+      "jsonl:event"
+    ]
+  ]
+};
+var tsvBaerschLog = {
+  in: (0, import_core.getEvent)("page view", {
+    timestamp: 17e11,
+    data: { title: "Docs" },
+    user: { session: "sess-1" },
+    source: {
+      id: "https://example.com/docs",
+      type: "server",
+      previous_id: "https://example.com/"
+    }
+  }),
+  settings: {
+    filename: "storage/mblog.txt",
+    format: "tsv",
+    fields: [
+      "timestamp",
+      "user.session",
+      "name",
+      "source.id",
+      "data.title",
+      "source.previous_id"
+    ]
+  },
+  out: [
+    [
+      "fs.writeFile",
+      "storage/mblog.txt",
+      "1700000000000	sess-1	page view	https://example.com/docs	Docs	https://example.com/\n"
+    ]
+  ]
+};
+var jsonlTenantShardKey = {
+  in: (0, import_core.getEvent)("custom event", {
+    timestamp: 17e11,
+    data: { tenant: "acme" }
+  }),
+  settings: {
+    filename: { key: "data.tenant" },
+    format: "jsonl"
+  },
+  out: [["fs.writeFile", "acme", "jsonl:event"]]
+};
+var jsonlDailyRotation = {
+  in: (0, import_core.getEvent)("order complete", {
+    timestamp: Date.UTC(2026, 3, 15, 12, 34, 56),
+    data: { id: "ORD-1" }
+  }),
+  settings: {
+    filename: {
+      fn: (value) => {
+        var _a;
+        const event = value;
+        const ts = (_a = event.timestamp) != null ? _a : 0;
+        return `events-${new Date(ts).toISOString().slice(0, 10)}.jsonl`;
+      }
+    },
+    format: "jsonl"
+  },
+  out: [["fs.writeFile", "events-2026-04-15.jsonl", "jsonl:event"]]
+};
+var csvObjectCell = {
+  in: (0, import_core.getEvent)("page view", {
+    timestamp: 17e11,
+    data: { title: 'Hello, "World"', count: 3 }
+  }),
+  settings: {
+    filename: "events.csv",
+    format: "csv",
+    fields: ["timestamp", "name", "data"]
+  },
+  out: [
+    [
+      "fs.writeFile",
+      "events.csv",
+      '1700000000000,page view,"{""title"":""Hello, \\""World\\"""",""count"":3}"\n'
+    ]
+  ]
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  env,
+  step
+});

package/dist/examples/index.mjs

@@ -0,0 +1,156 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/examples/env.ts
+var env_exports = {};
+__export(env_exports, {
+  init: () => init,
+  push: () => push
+});
+function makeSpyEnv() {
+  const state = {
+    captured: /* @__PURE__ */ new Map(),
+    mkdirCalls: []
+  };
+  const createWriteStream = (path) => {
+    const existing = state.captured.get(path);
+    const file = existing != null ? existing : {
+      filename: path,
+      lines: [],
+      ended: false
+    };
+    if (!existing) state.captured.set(path, file);
+    const stream = {
+      write(chunk) {
+        file.lines.push(chunk);
+        return true;
+      },
+      end() {
+        file.ended = true;
+      }
+    };
+    return stream;
+  };
+  const mkdir = async (path) => {
+    state.mkdirCalls.push(path);
+  };
+  return {
+    _spy: state,
+    fs: {
+      createWriteStream,
+      mkdir
+    }
+  };
+}
+var init = makeSpyEnv();
+var push = makeSpyEnv();
+
+// src/examples/step.ts
+var step_exports = {};
+__export(step_exports, {
+  csvObjectCell: () => csvObjectCell,
+  jsonlDailyRotation: () => jsonlDailyRotation,
+  jsonlDefault: () => jsonlDefault,
+  jsonlTenantShardKey: () => jsonlTenantShardKey,
+  tsvBaerschLog: () => tsvBaerschLog
+});
+import { getEvent } from "@walkeros/core";
+var jsonlDefault = {
+  in: getEvent("page view", { timestamp: 17e11 }),
+  settings: { filename: "events.jsonl" },
+  out: [
+    [
+      "fs.writeFile",
+      "events.jsonl",
+      // JSONL framework contract: JSON.stringify(event) + '\n'.
+      // The test recomputes this from example.in for the jsonl default to
+      // avoid duplicating the full event shape here.
+      "jsonl:event"
+    ]
+  ]
+};
+var tsvBaerschLog = {
+  in: getEvent("page view", {
+    timestamp: 17e11,
+    data: { title: "Docs" },
+    user: { session: "sess-1" },
+    source: {
+      id: "https://example.com/docs",
+      type: "server",
+      previous_id: "https://example.com/"
+    }
+  }),
+  settings: {
+    filename: "storage/mblog.txt",
+    format: "tsv",
+    fields: [
+      "timestamp",
+      "user.session",
+      "name",
+      "source.id",
+      "data.title",
+      "source.previous_id"
+    ]
+  },
+  out: [
+    [
+      "fs.writeFile",
+      "storage/mblog.txt",
+      "1700000000000	sess-1	page view	https://example.com/docs	Docs	https://example.com/\n"
+    ]
+  ]
+};
+var jsonlTenantShardKey = {
+  in: getEvent("custom event", {
+    timestamp: 17e11,
+    data: { tenant: "acme" }
+  }),
+  settings: {
+    filename: { key: "data.tenant" },
+    format: "jsonl"
+  },
+  out: [["fs.writeFile", "acme", "jsonl:event"]]
+};
+var jsonlDailyRotation = {
+  in: getEvent("order complete", {
+    timestamp: Date.UTC(2026, 3, 15, 12, 34, 56),
+    data: { id: "ORD-1" }
+  }),
+  settings: {
+    filename: {
+      fn: (value) => {
+        var _a;
+        const event = value;
+        const ts = (_a = event.timestamp) != null ? _a : 0;
+        return `events-${new Date(ts).toISOString().slice(0, 10)}.jsonl`;
+      }
+    },
+    format: "jsonl"
+  },
+  out: [["fs.writeFile", "events-2026-04-15.jsonl", "jsonl:event"]]
+};
+var csvObjectCell = {
+  in: getEvent("page view", {
+    timestamp: 17e11,
+    data: { title: 'Hello, "World"', count: 3 }
+  }),
+  settings: {
+    filename: "events.csv",
+    format: "csv",
+    fields: ["timestamp", "name", "data"]
+  },
+  out: [
+    [
+      "fs.writeFile",
+      "events.csv",
+      '1700000000000,page view,"{""title"":""Hello, \\""World\\"""",""count"":3}"\n'
+    ]
+  ]
+};
+export {
+  env_exports as env,
+  step_exports as step
+};

package/dist/index.d.mts

@@ -0,0 +1,78 @@
+import { Mapping as Mapping$1, Destination as Destination$1 } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+import { WriteStream } from 'node:fs';
+
+type Format = 'jsonl' | 'tsv' | 'csv';
+interface Settings {
+    /**
+     * Output filename. Either a static string or a Mapping.Value resolved
+     * per event (e.g. tenant sharding via `key`, daily rotation via `$code:` fn).
+     * Static filenames are validated and opened at flow startup;
+     * dynamic ones at first matching event.
+     */
+    filename: string | Mapping$1.Value;
+    /** Serialisation format. Defaults to 'jsonl'. */
+    format?: Format;
+    /**
+     * Event paths used as columns for tsv/csv formats. Order preserved.
+     * Object values are JSON-stringified into a single cell.
+     * Required when format is 'tsv' or 'csv'.
+     */
+    fields?: string[];
+}
+type InitSettings = Partial<Settings>;
+interface Mapping {
+}
+/**
+ * Minimal write-stream interface used by the destination. Matches the
+ * subset of node:fs WriteStream needed for append-only writes. Tests
+ * inject a fake implementation via env.fs.
+ */
+interface FileWriteStream {
+    write: (chunk: string) => boolean;
+    end: () => void;
+}
+interface Env extends DestinationServer.Env {
+    /**
+     * Override the file system primitives. Tests inject a fake here so
+     * disk writes are captured in memory.
+     */
+    fs?: {
+        createWriteStream: (path: string, options: {
+            flags: string;
+        }) => FileWriteStream | WriteStream;
+        mkdir: (path: string, options: {
+            recursive: boolean;
+        }) => Promise<void>;
+    };
+}
+type Types = Destination$1.Types<Settings, Mapping, Env, InitSettings>;
+interface Destination extends DestinationServer.Destination<Types> {
+    init: DestinationServer.InitFn<Types>;
+}
+type Config = {
+    settings: Settings;
+} & DestinationServer.Config<Types>;
+type PartialConfig = DestinationServer.PartialConfig<Types>;
+type InitFn = DestinationServer.InitFn<Types>;
+type PushFn = DestinationServer.PushFn<Types>;
+
+type index_Config = Config;
+type index_Destination = Destination;
+type index_Env = Env;
+type index_FileWriteStream = FileWriteStream;
+type index_Format = Format;
+type index_InitFn = InitFn;
+type index_InitSettings = InitSettings;
+type index_Mapping = Mapping;
+type index_PartialConfig = PartialConfig;
+type index_PushFn = PushFn;
+type index_Settings = Settings;
+type index_Types = Types;
+declare namespace index {
+  export type { index_Config as Config, index_Destination as Destination, index_Env as Env, index_FileWriteStream as FileWriteStream, index_Format as Format, index_InitFn as InitFn, index_InitSettings as InitSettings, index_Mapping as Mapping, index_PartialConfig as PartialConfig, index_PushFn as PushFn, index_Settings as Settings, index_Types as Types };
+}
+
+declare const destinationFile: Destination;
+
+export { index as DestinationFile, destinationFile as default, destinationFile };

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { Mapping as Mapping$1, Destination as Destination$1 } from '@walkeros/core';
+import { DestinationServer } from '@walkeros/server-core';
+import { WriteStream } from 'node:fs';
+
+type Format = 'jsonl' | 'tsv' | 'csv';
+interface Settings {
+    /**
+     * Output filename. Either a static string or a Mapping.Value resolved
+     * per event (e.g. tenant sharding via `key`, daily rotation via `$code:` fn).
+     * Static filenames are validated and opened at flow startup;
+     * dynamic ones at first matching event.
+     */
+    filename: string | Mapping$1.Value;
+    /** Serialisation format. Defaults to 'jsonl'. */
+    format?: Format;
+    /**
+     * Event paths used as columns for tsv/csv formats. Order preserved.
+     * Object values are JSON-stringified into a single cell.
+     * Required when format is 'tsv' or 'csv'.
+     */
+    fields?: string[];
+}
+type InitSettings = Partial<Settings>;
+interface Mapping {
+}
+/**
+ * Minimal write-stream interface used by the destination. Matches the
+ * subset of node:fs WriteStream needed for append-only writes. Tests
+ * inject a fake implementation via env.fs.
+ */
+interface FileWriteStream {
+    write: (chunk: string) => boolean;
+    end: () => void;
+}
+interface Env extends DestinationServer.Env {
+    /**
+     * Override the file system primitives. Tests inject a fake here so
+     * disk writes are captured in memory.
+     */
+    fs?: {
+        createWriteStream: (path: string, options: {
+            flags: string;
+        }) => FileWriteStream | WriteStream;
+        mkdir: (path: string, options: {
+            recursive: boolean;
+        }) => Promise<void>;
+    };
+}
+type Types = Destination$1.Types<Settings, Mapping, Env, InitSettings>;
+interface Destination extends DestinationServer.Destination<Types> {
+    init: DestinationServer.InitFn<Types>;
+}
+type Config = {
+    settings: Settings;
+} & DestinationServer.Config<Types>;
+type PartialConfig = DestinationServer.PartialConfig<Types>;
+type InitFn = DestinationServer.InitFn<Types>;
+type PushFn = DestinationServer.PushFn<Types>;
+
+type index_Config = Config;
+type index_Destination = Destination;
+type index_Env = Env;
+type index_FileWriteStream = FileWriteStream;
+type index_Format = Format;
+type index_InitFn = InitFn;
+type index_InitSettings = InitSettings;
+type index_Mapping = Mapping;
+type index_PartialConfig = PartialConfig;
+type index_PushFn = PushFn;
+type index_Settings = Settings;
+type index_Types = Types;
+declare namespace index {
+  export type { index_Config as Config, index_Destination as Destination, index_Env as Env, index_FileWriteStream as FileWriteStream, index_Format as Format, index_InitFn as InitFn, index_InitSettings as InitSettings, index_Mapping as Mapping, index_PartialConfig as PartialConfig, index_PushFn as PushFn, index_Settings as Settings, index_Types as Types };
+}
+
+declare const destinationFile: Destination;
+
+export { index as DestinationFile, destinationFile as default, destinationFile };

package/dist/index.js

@@ -0,0 +1 @@
+"use strict";var mod,__defProp=Object.defineProperty,__getOwnPropDesc=Object.getOwnPropertyDescriptor,__getOwnPropNames=Object.getOwnPropertyNames,__hasOwnProp=Object.prototype.hasOwnProperty,index_exports={};((target,all)=>{for(var name in all)__defProp(target,name,{get:all[name],enumerable:!0})})(index_exports,{DestinationFile:()=>types_exports,default:()=>index_default,destinationFile:()=>destinationFile}),module.exports=(mod=index_exports,((to,from,except,desc)=>{if(from&&"object"==typeof from||"function"==typeof from)for(let key of __getOwnPropNames(from))__hasOwnProp.call(to,key)||key===except||__defProp(to,key,{get:()=>from[key],enumerable:!(desc=__getOwnPropDesc(from,key))||desc.enumerable});return to})(__defProp({},"__esModule",{value:!0}),mod));var import_core2=require("@walkeros/core"),import_node_fs=require("fs"),import_promises=require("fs/promises"),import_node_path=require("path"),import_core=require("@walkeros/core");async function ensureHandle(state,filename){const cached=state.handles.get(filename);if(cached)return cached;await state.fs.mkdir((0,import_node_path.dirname)(filename)||".",{recursive:!0});const handle=state.fs.createWriteStream(filename,{flags:"a"});return state.handles.set(filename,handle),handle}function serialize(event,format,fields){if("jsonl"===format)return JSON.stringify(event)+"\n";if(!fields||0===fields.length)throw new Error(`file destination: format '${format}' requires non-empty 'fields' setting`);const cells=fields.map(path=>{return null==(value=(0,import_core.getByPath)(event,path))?"":(0,import_core.isObject)(value)||Array.isArray(value)?JSON.stringify(value):"string"==typeof value?value:"number"==typeof value||"boolean"==typeof value?String(value):JSON.stringify(value);var value});return"tsv"===format?cells.join("\t")+"\n":cells.map(csvEscape).join(",")+"\n"}function csvEscape(value){return/[",\r\n]/.test(value)?`"${value.replace(/"/g,'""')}"`:value}var states=new Map;function getState(id){return states.get(id)}var types_exports={},destinationFile={type:"file",config:{},init:async({id:id,config:config,env:env,logger:logger})=>{var _a,_b;const partial=null!=(_a=null==config?void 0:config.settings)?_a:{};if(void 0===partial.filename||null===partial.filename)return logger.throw("file destination: 'filename' is required (string or Mapping.Value)"),!1;if(!(0,import_core2.isString)(partial.filename)&&!(0,import_core2.isObject)(partial.filename)&&!Array.isArray(partial.filename))return logger.throw("file destination: 'filename' must be a string or a Mapping.Value"),!1;const format=null!=(_b=partial.format)?_b:"jsonl";if(!("tsv"!==format&&"csv"!==format||partial.fields&&0!==partial.fields.length))return logger.throw(`file destination: format '${format}' requires non-empty 'fields'`),!1;const settings={filename:partial.filename,format:format,fields:partial.fields},state=function(env){const fsOverride=null==env?void 0:env.fs,defaultFs={createWriteStream:(path,options)=>(0,import_node_fs.createWriteStream)(path,options),mkdir:async(path,options)=>{await(0,import_promises.mkdir)(path,options)}};return{handles:new Map,fs:null!=fsOverride?fsOverride:defaultFs}}(env);if((0,import_core2.isString)(settings.filename))try{await ensureHandle(state,settings.filename)}catch(err){return logger.throw(`file destination: failed to open '${settings.filename}': ${err instanceof Error?err.message:String(err)}`),!1}return function(id,state){states.set(id,state)}(id,state),{...config,settings:settings}},push:async(event,{id:id,config:config,collector:collector,logger:logger})=>{var _a;const settings=config.settings;if(!settings)return void logger.warn("file destination: settings missing");const state=getState(id);if(!state)return void logger.warn("file destination: state missing, init may have failed");let filename;if((0,import_core2.isString)(settings.filename))filename=settings.filename;else{const resolved=await(0,import_core2.getMappingValue)(event,settings.filename,{collector:collector});if(!(0,import_core2.isString)(resolved)||0===resolved.length)return void logger.warn("file destination: dynamic filename resolved to empty or non-string, dropping event");filename=resolved}try{(await ensureHandle(state,filename)).write(serialize(event,null!=(_a=settings.format)?_a:"jsonl",settings.fields))}catch(err){logger.warn(`file destination: write failed for ${filename}: ${err instanceof Error?err.message:String(err)}`)}},async destroy({id:id}){const state=getState(id);if(state){for(const handle of state.handles.values())try{handle.end()}catch(e){}state.handles.clear(),function(id){states.delete(id)}(id)}}},index_default=destinationFile;//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/helpers.ts","../src/types/index.ts"],"sourcesContent":["import { getMappingValue, isString, isObject } from '@walkeros/core';\nimport type { Destination, InitFn, PushFn, Settings } from './types';\nimport {\n  createState,\n  ensureHandle,\n  getState,\n  registerState,\n  removeState,\n  serialize,\n} from './helpers';\n\nexport * as DestinationFile from './types';\n\nconst init: InitFn = async ({ id, config, env, logger }) => {\n  const partial = (config?.settings ?? {}) as Partial<Settings>;\n  if (partial.filename === undefined || partial.filename === null) {\n    logger.throw(\n      \"file destination: 'filename' is required (string or Mapping.Value)\",\n    );\n    return false;\n  }\n  if (\n    !isString(partial.filename) &&\n    !(isObject(partial.filename) || Array.isArray(partial.filename))\n  ) {\n    logger.throw(\n      \"file destination: 'filename' must be a string or a Mapping.Value\",\n    );\n    return false;\n  }\n\n  const format = partial.format ?? 'jsonl';\n  if (\n    (format === 'tsv' || format === 'csv') &&\n    (!partial.fields || partial.fields.length === 0)\n  ) {\n    logger.throw(\n      `file destination: format '${format}' requires non-empty 'fields'`,\n    );\n    return false;\n  }\n\n  const settings: Settings = {\n    filename: partial.filename,\n    format,\n    fields: partial.fields,\n  };\n\n  const state = createState(env);\n\n  // Eager open for static filename — fail-fast on bad path.\n  if (isString(settings.filename)) {\n    try {\n      await ensureHandle(state, settings.filename);\n    } catch (err) {\n      logger.throw(\n        `file destination: failed to open '${settings.filename}': ${\n          err instanceof Error ? err.message : String(err)\n        }`,\n      );\n      return false;\n    }\n  }\n\n  registerState(id, state);\n\n  return {\n    ...config,\n    settings,\n  };\n};\n\nconst push: PushFn = async (event, { id, config, collector, logger }) => {\n  const settings = config.settings as Settings | undefined;\n  if (!settings) {\n    logger.warn('file destination: settings missing');\n    return;\n  }\n  const state = getState(id);\n  if (!state) {\n    logger.warn('file destination: state missing, init may have failed');\n    return;\n  }\n\n  let filename: string;\n  if (isString(settings.filename)) {\n    filename = settings.filename;\n  } else {\n    const resolved = await getMappingValue(event, settings.filename, {\n      collector,\n    });\n    if (!isString(resolved) || resolved.length === 0) {\n      logger.warn(\n        'file destination: dynamic filename resolved to empty or non-string, dropping event',\n      );\n      return;\n    }\n    filename = resolved;\n  }\n\n  try {\n    const handle = await ensureHandle(state, filename);\n    handle.write(serialize(event, settings.format ?? 'jsonl', settings.fields));\n  } catch (err) {\n    logger.warn(\n      `file destination: write failed for ${filename}: ${\n        err instanceof Error ? err.message : String(err)\n      }`,\n    );\n  }\n};\n\nexport const destinationFile: Destination = {\n  type: 'file',\n\n  config: {},\n\n  init,\n\n  push,\n\n  async destroy({ id }) {\n    const state = getState(id);\n    if (!state) return;\n    for (const handle of state.handles.values()) {\n      try {\n        handle.end();\n      } catch {\n        // idempotent — ignore end errors on already-closed streams\n      }\n    }\n    state.handles.clear();\n    removeState(id);\n  },\n};\n\nexport default destinationFile;\n","import {\n  createWriteStream as nodeCreateWriteStream,\n  type WriteStream,\n} from 'node:fs';\nimport { mkdir as nodeMkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\nimport { getByPath, isObject } from '@walkeros/core';\nimport type { WalkerOS } from '@walkeros/core';\nimport type { Env, FileWriteStream, Format } from './types';\n\n/**\n * State held per destination instance. Created in init(), reused by\n * push() and destroy(). Keyed by a stable instance id so tests and\n * hot-swap do not share handles across instances.\n */\nexport interface State {\n  handles: Map<string, FileWriteStream>;\n  fs: NonNullable<Env['fs']>;\n}\n\nexport function createState(env: Env | undefined): State {\n  const fsOverride = env?.fs;\n  const defaultFs: NonNullable<Env['fs']> = {\n    createWriteStream: (path: string, options: { flags: string }) =>\n      nodeCreateWriteStream(path, options),\n    mkdir: async (path: string, options: { recursive: boolean }) => {\n      await nodeMkdir(path, options);\n    },\n  };\n  return {\n    handles: new Map(),\n    fs: fsOverride ?? defaultFs,\n  };\n}\n\n/**\n * Idempotent open-or-cache. Ensures the parent directory exists and\n * appends to the file via flag 'a' (creates the file if missing).\n * Used by both init() (eager static open) and push() (lazy per-event open).\n */\nexport async function ensureHandle(\n  state: State,\n  filename: string,\n): Promise<FileWriteStream> {\n  const cached = state.handles.get(filename);\n  if (cached) return cached;\n  await state.fs.mkdir(dirname(filename) || '.', { recursive: true });\n  const handle = state.fs.createWriteStream(filename, {\n    flags: 'a',\n  }) as FileWriteStream | WriteStream;\n  state.handles.set(filename, handle);\n  return handle;\n}\n\n/**\n * Format an event into a single output line (with trailing newline).\n * One implementation, used by push() for all three formats.\n */\nexport function serialize(\n  event: WalkerOS.Event,\n  format: Format,\n  fields: string[] | undefined,\n): string {\n  if (format === 'jsonl') {\n    return JSON.stringify(event) + '\\n';\n  }\n  if (!fields || fields.length === 0) {\n    throw new Error(\n      `file destination: format '${format}' requires non-empty 'fields' setting`,\n    );\n  }\n  const cells = fields.map((path) =>\n    formatCell(getByPath(event as unknown as WalkerOS.Properties, path)),\n  );\n  if (format === 'tsv') {\n    return cells.join('\\t') + '\\n';\n  }\n  // csv\n  return cells.map(csvEscape).join(',') + '\\n';\n}\n\nfunction formatCell(value: unknown): string {\n  if (value === null || value === undefined) return '';\n  if (isObject(value) || Array.isArray(value)) return JSON.stringify(value);\n  if (typeof value === 'string') return value;\n  if (typeof value === 'number' || typeof value === 'boolean')\n    return String(value);\n  return JSON.stringify(value);\n}\n\n/**\n * RFC 4180 CSV escaping: wrap in quotes if the value contains\n * comma, quote, CR, or LF; double up internal quotes.\n */\nfunction csvEscape(value: string): string {\n  if (/[\",\\r\\n]/.test(value)) {\n    return `\"${value.replace(/\"/g, '\"\"')}\"`;\n  }\n  return value;\n}\n\n/**\n * Module-level state map keyed by destination instance id. Plan Task 5\n * documents this as the fallback to config-attached symbols. Each\n * destination instance has a unique id; destroy() removes its entry.\n */\nconst states = new Map<string, State>();\n\nexport function registerState(id: string, state: State): void {\n  states.set(id, state);\n}\n\nexport function getState(id: string): State | undefined {\n  return states.get(id);\n}\n\nexport function removeState(id: string): void {\n  states.delete(id);\n}\n","import type {\n  Destination as CoreDestination,\n  Mapping as CoreMapping,\n} from '@walkeros/core';\nimport type { DestinationServer } from '@walkeros/server-core';\nimport type { WriteStream } from 'node:fs';\n\nexport type Format = 'jsonl' | 'tsv' | 'csv';\n\nexport interface Settings {\n  /**\n   * Output filename. Either a static string or a Mapping.Value resolved\n   * per event (e.g. tenant sharding via `key`, daily rotation via `$code:` fn).\n   * Static filenames are validated and opened at flow startup;\n   * dynamic ones at first matching event.\n   */\n  filename: string | CoreMapping.Value;\n\n  /** Serialisation format. Defaults to 'jsonl'. */\n  format?: Format;\n\n  /**\n   * Event paths used as columns for tsv/csv formats. Order preserved.\n   * Object values are JSON-stringified into a single cell.\n   * Required when format is 'tsv' or 'csv'.\n   */\n  fields?: string[];\n}\n\nexport type InitSettings = Partial<Settings>;\n\nexport interface Mapping {}\n\n/**\n * Minimal write-stream interface used by the destination. Matches the\n * subset of node:fs WriteStream needed for append-only writes. Tests\n * inject a fake implementation via env.fs.\n */\nexport interface FileWriteStream {\n  write: (chunk: string) => boolean;\n  end: () => void;\n}\n\nexport interface Env extends DestinationServer.Env {\n  /**\n   * Override the file system primitives. Tests inject a fake here so\n   * disk writes are captured in memory.\n   */\n  fs?: {\n    createWriteStream: (\n      path: string,\n      options: { flags: string },\n    ) => FileWriteStream | WriteStream;\n    mkdir: (path: string, options: { recursive: boolean }) => Promise<void>;\n  };\n}\n\nexport type Types = CoreDestination.Types<Settings, Mapping, Env, InitSettings>;\n\nexport interface Destination extends DestinationServer.Destination<Types> {\n  init: DestinationServer.InitFn<Types>;\n}\n\nexport type Config = {\n  settings: Settings;\n} & DestinationServer.Config<Types>;\n\nexport type PartialConfig = DestinationServer.PartialConfig<Types>;\nexport type InitFn = DestinationServer.InitFn<Types>;\nexport type PushFn = DestinationServer.PushFn<Types>;\n"],"mappings":"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","names":["import_core","nodeCreateWriteStream","nodeMkdir"]}

package/dist/index.mjs

@@ -0,0 +1 @@
+import{getMappingValue,isString,isObject as isObject2}from"@walkeros/core";import{createWriteStream as nodeCreateWriteStream}from"fs";import{mkdir as nodeMkdir}from"fs/promises";import{dirname}from"path";import{getByPath,isObject}from"@walkeros/core";async function ensureHandle(state,filename){const cached=state.handles.get(filename);if(cached)return cached;await state.fs.mkdir(dirname(filename)||".",{recursive:!0});const handle=state.fs.createWriteStream(filename,{flags:"a"});return state.handles.set(filename,handle),handle}function serialize(event,format,fields){if("jsonl"===format)return JSON.stringify(event)+"\n";if(!fields||0===fields.length)throw new Error(`file destination: format '${format}' requires non-empty 'fields' setting`);const cells=fields.map(path=>{return null==(value=getByPath(event,path))?"":isObject(value)||Array.isArray(value)?JSON.stringify(value):"string"==typeof value?value:"number"==typeof value||"boolean"==typeof value?String(value):JSON.stringify(value);var value});return"tsv"===format?cells.join("\t")+"\n":cells.map(csvEscape).join(",")+"\n"}function csvEscape(value){return/[",\r\n]/.test(value)?`"${value.replace(/"/g,'""')}"`:value}var states=new Map;function getState(id){return states.get(id)}var types_exports={},destinationFile={type:"file",config:{},init:async({id:id,config:config,env:env,logger:logger})=>{var _a,_b;const partial=null!=(_a=null==config?void 0:config.settings)?_a:{};if(void 0===partial.filename||null===partial.filename)return logger.throw("file destination: 'filename' is required (string or Mapping.Value)"),!1;if(!isString(partial.filename)&&!isObject2(partial.filename)&&!Array.isArray(partial.filename))return logger.throw("file destination: 'filename' must be a string or a Mapping.Value"),!1;const format=null!=(_b=partial.format)?_b:"jsonl";if(!("tsv"!==format&&"csv"!==format||partial.fields&&0!==partial.fields.length))return logger.throw(`file destination: format '${format}' requires non-empty 'fields'`),!1;const settings={filename:partial.filename,format:format,fields:partial.fields},state=function(env){const fsOverride=null==env?void 0:env.fs,defaultFs={createWriteStream:(path,options)=>nodeCreateWriteStream(path,options),mkdir:async(path,options)=>{await nodeMkdir(path,options)}};return{handles:new Map,fs:null!=fsOverride?fsOverride:defaultFs}}(env);if(isString(settings.filename))try{await ensureHandle(state,settings.filename)}catch(err){return logger.throw(`file destination: failed to open '${settings.filename}': ${err instanceof Error?err.message:String(err)}`),!1}return function(id,state){states.set(id,state)}(id,state),{...config,settings:settings}},push:async(event,{id:id,config:config,collector:collector,logger:logger})=>{var _a;const settings=config.settings;if(!settings)return void logger.warn("file destination: settings missing");const state=getState(id);if(!state)return void logger.warn("file destination: state missing, init may have failed");let filename;if(isString(settings.filename))filename=settings.filename;else{const resolved=await getMappingValue(event,settings.filename,{collector:collector});if(!isString(resolved)||0===resolved.length)return void logger.warn("file destination: dynamic filename resolved to empty or non-string, dropping event");filename=resolved}try{(await ensureHandle(state,filename)).write(serialize(event,null!=(_a=settings.format)?_a:"jsonl",settings.fields))}catch(err){logger.warn(`file destination: write failed for ${filename}: ${err instanceof Error?err.message:String(err)}`)}},async destroy({id:id}){const state=getState(id);if(state){for(const handle of state.handles.values())try{handle.end()}catch(e){}state.handles.clear(),function(id){states.delete(id)}(id)}}},index_default=destinationFile;export{types_exports as DestinationFile,index_default as default,destinationFile};//# sourceMappingURL=index.mjs.map