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

package/README.md

@@ -0,0 +1,97 @@
+# @walkeros/server-destination-file
+
+Local file sink for walkerOS server flows. Appends events to a file in JSONL,
+TSV, or CSV format. Useful for debug logging, audit trails, replay sources, and
+lightweight local persistence without standing up a database.
+
+## Install
+
+```bash
+npm install @walkeros/server-destination-file
+```
+
+## Usage
+
+Add to your `flow.json`:
+
+```json
+{
+  "destinations": {
+    "log": {
+      "package": "@walkeros/server-destination-file",
+      "config": {
+        "settings": {
+          "filename": "events.jsonl"
+        }
+      }
+    }
+  }
+}
+```
+
+Every event gets appended as a JSON line. The file and its parent directory are
+created on flow startup.
+
+## Settings
+
+| Field      | Type                        | Default              | Notes                                                       |
+| ---------- | --------------------------- | -------------------- | ----------------------------------------------------------- |
+| `filename` | `string \| Mapping.Value`   | required             | Static path or per-event resolution via the mapping DSL.    |
+| `format`   | `'jsonl' \| 'tsv' \| 'csv'` | `jsonl`              | Serialisation format.                                       |
+| `fields`   | `string[]`                  | required for tsv/csv | Event paths used as columns. Object cells JSON-stringified. |
+
+## Filename templating
+
+`filename` accepts the standard walkerOS `Mapping.Value` shape.
+
+### Tenant sharding
+
+```json
+{ "filename": { "key": "data.tenant" } }
+```
+
+### Daily rotation
+
+```json
+{
+  "filename": {
+    "fn": "$code:`events-${new Date(value.timestamp).toISOString().slice(0,10)}.jsonl`"
+  }
+}
+```
+
+Inside the `$code:` function, `value` is the event being processed.
+
+## Formats
+
+### JSONL (default)
+
+One JSON object per line. Ingest with `jq`, `duckdb`, ClickHouse `JSONEachRow`,
+BigQuery external tables, Athena.
+
+### TSV / CSV
+
+Specify `fields: string[]` listing the event paths to extract as columns. Object
+values are JSON-stringified into a single cell. RFC 4180 quoting for CSV.
+
+```json
+{
+  "filename": "events.csv",
+  "format": "csv",
+  "fields": ["timestamp", "name", "data"]
+}
+```
+
+## Limits
+
+- One file handle is opened per resolved filename and kept open until
+  `destroy()`. Sharding by high-cardinality keys (e.g. `user.session`) can
+  exhaust OS file descriptors.
+- External rotation (e.g. `logrotate`) leaves the cached handle pointing at the
+  rotated inode. Use the date-token pattern instead.
+- No batching. Each event is `stream.write`'d individually.
+- Write errors log a warning and drop the event — they never fail the flow.
+
+## License
+
+MIT

package/dist/dev.d.mts

@@ -0,0 +1,148 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { DestinationServer } from '@walkeros/server-core';
+import { WriteStream } from 'node:fs';
+import { Flow } from '@walkeros/core';
+
+declare const SettingsSchema: z.ZodObject<{
+    filename: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+    format: z.ZodOptional<z.ZodEnum<{
+        jsonl: "jsonl";
+        tsv: "tsv";
+        csv: "csv";
+    }>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{}, z.core.$strip>;
+type Mapping = z.infer<typeof MappingSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const mapping: _walkeros_core_dev.JSONSchema;
+
+type index$1_Mapping = Mapping;
+declare const index$1_MappingSchema: typeof MappingSchema;
+type index$1_Settings = Settings;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_mapping: typeof mapping;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  export { type index$1_Mapping as Mapping, index$1_MappingSchema as MappingSchema, type index$1_Settings as Settings, index$1_SettingsSchema as SettingsSchema, index$1_mapping as mapping, index$1_settings as settings };
+}
+
+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 };
+}
+
+declare const index_env: typeof env;
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_env as env, index_step as step };
+}
+
+export { index as examples, index$1 as schemas };

package/dist/dev.d.ts

@@ -0,0 +1,148 @@
+import * as _walkeros_core_dev from '@walkeros/core/dev';
+import { z } from '@walkeros/core/dev';
+import { DestinationServer } from '@walkeros/server-core';
+import { WriteStream } from 'node:fs';
+import { Flow } from '@walkeros/core';
+
+declare const SettingsSchema: z.ZodObject<{
+    filename: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+    format: z.ZodOptional<z.ZodEnum<{
+        jsonl: "jsonl";
+        tsv: "tsv";
+        csv: "csv";
+    }>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type Settings = z.infer<typeof SettingsSchema>;
+
+declare const MappingSchema: z.ZodObject<{}, z.core.$strip>;
+type Mapping = z.infer<typeof MappingSchema>;
+
+declare const settings: _walkeros_core_dev.JSONSchema;
+declare const mapping: _walkeros_core_dev.JSONSchema;
+
+type index$1_Mapping = Mapping;
+declare const index$1_MappingSchema: typeof MappingSchema;
+type index$1_Settings = Settings;
+declare const index$1_SettingsSchema: typeof SettingsSchema;
+declare const index$1_mapping: typeof mapping;
+declare const index$1_settings: typeof settings;
+declare namespace index$1 {
+  export { type index$1_Mapping as Mapping, index$1_MappingSchema as MappingSchema, type index$1_Settings as Settings, index$1_SettingsSchema as SettingsSchema, index$1_mapping as mapping, index$1_settings as settings };
+}
+
+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 };
+}
+
+declare const index_env: typeof env;
+declare const index_step: typeof step;
+declare namespace index {
+  export { index_env as env, index_step as step };
+}
+
+export { index as examples, index$1 as schemas };

package/dist/dev.js

@@ -0,0 +1 @@
+"use strict";var e,t=Object.defineProperty,s=Object.getOwnPropertyDescriptor,n=Object.getOwnPropertyNames,a=Object.prototype.hasOwnProperty,r=(e,s)=>{for(var n in s)t(e,n,{get:s[n],enumerable:!0})},o={};r(o,{examples:()=>v,schemas:()=>i}),module.exports=(e=o,((e,r,o,i)=>{if(r&&"object"==typeof r||"function"==typeof r)for(let l of n(r))a.call(e,l)||l===o||t(e,l,{get:()=>r[l],enumerable:!(i=s(r,l))||i.enumerable});return e})(t({},"__esModule",{value:!0}),e));var i={};r(i,{MappingSchema:()=>p,SettingsSchema:()=>m,mapping:()=>u,settings:()=>d});var l=require("@walkeros/core/dev"),c=require("@walkeros/core/dev"),m=c.z.object({filename:c.z.union([c.z.string().describe("Static output filename."),c.z.record(c.z.string(),c.z.unknown()).describe('Mapping.Value resolved per event (e.g. { key: "data.tenant" } or { fn: "$code:..." }).')]).describe('Output filename. Static string or Mapping.Value (e.g. { fn: "$code:..." } for daily rotation, { key: "data.tenant" } for sharding).'),format:c.z.enum(["jsonl","tsv","csv"]).optional().describe("Serialisation format. Defaults to jsonl."),fields:c.z.array(c.z.string()).optional().describe("Event paths used as columns for tsv/csv formats. Object values are JSON-stringified. Required when format is tsv or csv.")}),p=require("@walkeros/core/dev").z.object({}).describe("No per-rule overrides for the file destination."),d=(0,l.zodToSchema)(m),u=(0,l.zodToSchema)(p),v={};r(v,{env:()=>f,step:()=>b});var f={};function g(){const e={captured:new Map,mkdirCalls:[]};return{_spy:e,fs:{createWriteStream:t=>{const s=e.captured.get(t),n=null!=s?s:{filename:t,lines:[],ended:!1};s||e.captured.set(t,n);return{write:e=>(n.lines.push(e),!0),end(){n.ended=!0}}},mkdir:async t=>{e.mkdirCalls.push(t)}}}}r(f,{init:()=>j,push:()=>w});var j=g(),w=g(),b={};r(b,{csvObjectCell:()=>k,jsonlDailyRotation:()=>z,jsonlDefault:()=>y,jsonlTenantShardKey:()=>S,tsvBaerschLog:()=>O});var h=require("@walkeros/core"),y={in:(0,h.getEvent)("page view",{timestamp:17e11}),settings:{filename:"events.jsonl"},out:[["fs.writeFile","events.jsonl","jsonl:event"]]},O={in:(0,h.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\tsess-1\tpage view\thttps://example.com/docs\tDocs\thttps://example.com/\n"]]},S={in:(0,h.getEvent)("custom event",{timestamp:17e11,data:{tenant:"acme"}}),settings:{filename:{key:"data.tenant"},format:"jsonl"},out:[["fs.writeFile","acme","jsonl:event"]]},z={in:(0,h.getEvent)("order complete",{timestamp:Date.UTC(2026,3,15,12,34,56),data:{id:"ORD-1"}}),settings:{filename:{fn:e=>{var t;const s=null!=(t=e.timestamp)?t:0;return`events-${new Date(s).toISOString().slice(0,10)}.jsonl`}},format:"jsonl"},out:[["fs.writeFile","events-2026-04-15.jsonl","jsonl:event"]]},k={in:(0,h.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']]};//# sourceMappingURL=dev.js.map

package/dist/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/dev.ts","../src/schemas/index.ts","../src/schemas/settings.ts","../src/schemas/mapping.ts","../src/examples/index.ts","../src/examples/env.ts","../src/examples/step.ts"],"sourcesContent":["export * as schemas from './schemas';\nexport * as examples from './examples';\n","import { zodToSchema } from '@walkeros/core/dev';\nimport { SettingsSchema } from './settings';\nimport { MappingSchema } from './mapping';\n\nexport { SettingsSchema, type Settings } from './settings';\nexport { MappingSchema, type Mapping } from './mapping';\n\n// JSON Schema\nexport const settings = zodToSchema(SettingsSchema);\nexport const mapping = zodToSchema(MappingSchema);\n","import { z } from '@walkeros/core/dev';\n\nexport const SettingsSchema = z.object({\n  filename: z\n    .union([\n      z.string().describe('Static output filename.'),\n      z\n        .record(z.string(), z.unknown())\n        .describe(\n          'Mapping.Value resolved per event (e.g. { key: \"data.tenant\" } or { fn: \"$code:...\" }).',\n        ),\n    ])\n    .describe(\n      'Output filename. Static string or Mapping.Value (e.g. { fn: \"$code:...\" } for daily rotation, { key: \"data.tenant\" } for sharding).',\n    ),\n  format: z\n    .enum(['jsonl', 'tsv', 'csv'])\n    .optional()\n    .describe('Serialisation format. Defaults to jsonl.'),\n  fields: z\n    .array(z.string())\n    .optional()\n    .describe(\n      'Event paths used as columns for tsv/csv formats. Object values are JSON-stringified. Required when format is tsv or csv.',\n    ),\n});\n\nexport type Settings = z.infer<typeof SettingsSchema>;\n","import { z } from '@walkeros/core/dev';\n\nexport const MappingSchema = z\n  .object({})\n  .describe('No per-rule overrides for the file destination.');\n\nexport type Mapping = z.infer<typeof MappingSchema>;\n","export * as env from './env';\nexport * as step from './step';\n","import type { Env, FileWriteStream } from '../types';\n\n/**\n * Captured file state for assertions in tests.\n */\nexport interface CapturedFile {\n  filename: string;\n  lines: string[];\n  ended: boolean;\n}\n\n// Narrow helper type aliases so the mock fs is typed explicitly without `any`.\ntype CreateWriteStreamFn = (\n  path: string,\n  options: { flags: string },\n) => FileWriteStream;\ntype MkdirFn = (path: string, options: { recursive: boolean }) => Promise<void>;\n\nexport interface SpyState {\n  captured: Map<string, CapturedFile>;\n  mkdirCalls: string[];\n}\n\nexport interface SpyEnv extends Env {\n  _spy: SpyState;\n}\n\nfunction makeSpyEnv(): SpyEnv {\n  const state: SpyState = {\n    captured: new Map(),\n    mkdirCalls: [],\n  };\n\n  const createWriteStream: CreateWriteStreamFn = (path) => {\n    const existing = state.captured.get(path);\n    const file: CapturedFile = existing ?? {\n      filename: path,\n      lines: [],\n      ended: false,\n    };\n    if (!existing) state.captured.set(path, file);\n    const stream: FileWriteStream = {\n      write(chunk) {\n        file.lines.push(chunk);\n        return true;\n      },\n      end() {\n        file.ended = true;\n      },\n    };\n    return stream;\n  };\n\n  const mkdir: MkdirFn = async (path) => {\n    state.mkdirCalls.push(path);\n  };\n\n  return {\n    _spy: state,\n    fs: {\n      createWriteStream,\n      mkdir,\n    },\n  };\n}\n\nexport const init: SpyEnv = makeSpyEnv();\nexport const push: SpyEnv = makeSpyEnv();\n","import type { Flow } from '@walkeros/core';\nimport { getEvent } from '@walkeros/core';\nimport type { Format } from '../types';\n\n/**\n * Raw filename-config shape accepted in step examples and flow.json.\n * Mirrors the runtime Settings.filename but types `fn` as string so\n * `$code:` tags (resolved at bundle time by walkerOS) are expressible\n * here without casting to a function type.\n */\nexport interface FileSettingsJson {\n  filename:\n    | string\n    | {\n        key?: string;\n        fn?: string | ((value: unknown) => unknown);\n        value?: unknown;\n      };\n  format?: Format;\n  fields?: string[];\n}\n\n/**\n * Extended step example that carries destination-level settings for the\n * file destination.\n *\n * `out` is modeled at intent level as a single `['fs.writeFile', path, line]`\n * tuple per event (even though the destination internally uses a persistent\n * createWriteStream + write). This matches the design doc's preference for\n * readable intent-level callable tuples over stream-chain fidelity.\n *\n * Dropped / ignored events produce `out: []`.\n */\nexport type FileStepExample = Flow.StepExample & {\n  settings: FileSettingsJson;\n};\n\n/** Default JSONL append. Static filename, all defaults. */\nexport const jsonlDefault: FileStepExample = {\n  in: getEvent('page view', { timestamp: 1700000000000 }),\n  settings: { filename: 'events.jsonl' },\n  out: [\n    [\n      'fs.writeFile',\n      'events.jsonl',\n      // JSONL framework contract: JSON.stringify(event) + '\\n'.\n      // The test recomputes this from example.in for the jsonl default to\n      // avoid duplicating the full event shape here.\n      'jsonl:event',\n    ],\n  ],\n};\n\n/** Baersch-style TSV log: PHP parity case. */\nexport const tsvBaerschLog: FileStepExample = {\n  in: getEvent('page view', {\n    timestamp: 1700000000000,\n    data: { title: 'Docs' },\n    user: { session: 'sess-1' },\n    source: {\n      id: 'https://example.com/docs',\n      type: 'server',\n      previous_id: 'https://example.com/',\n    },\n  }),\n  settings: {\n    filename: 'storage/mblog.txt',\n    format: 'tsv',\n    fields: [\n      'timestamp',\n      'user.session',\n      'name',\n      'source.id',\n      'data.title',\n      'source.previous_id',\n    ],\n  },\n  out: [\n    [\n      'fs.writeFile',\n      'storage/mblog.txt',\n      '1700000000000\\tsess-1\\tpage view\\thttps://example.com/docs\\tDocs\\thttps://example.com/\\n',\n    ],\n  ],\n};\n\n/** Tenant sharding via plain key extraction. */\nexport const jsonlTenantShardKey: FileStepExample = {\n  in: getEvent('custom event', {\n    timestamp: 1700000000000,\n    data: { tenant: 'acme' },\n  }),\n  settings: {\n    filename: { key: 'data.tenant' },\n    format: 'jsonl',\n  },\n  out: [['fs.writeFile', 'acme', 'jsonl:event']],\n};\n\n/**\n * Daily rotation via a mapping fn. In flow.json this is authored as a\n * `$code:` string; walkerOS compiles it to a function at bundle time. For\n * in-process tests we pass the already-compiled function directly so the\n * example exercises the same code path without needing the bundler.\n */\nexport const jsonlDailyRotation: FileStepExample = {\n  in: getEvent('order complete', {\n    timestamp: Date.UTC(2026, 3, 15, 12, 34, 56),\n    data: { id: 'ORD-1' },\n  }),\n  settings: {\n    filename: {\n      fn: (value) => {\n        const event = value as { timestamp?: number };\n        const ts = event.timestamp ?? 0;\n        return `events-${new Date(ts).toISOString().slice(0, 10)}.jsonl`;\n      },\n    },\n    format: 'jsonl',\n  },\n  out: [['fs.writeFile', 'events-2026-04-15.jsonl', 'jsonl:event']],\n};\n\n/** CSV with an object cell. data is JSON-stringified, properly quoted. */\nexport const csvObjectCell: FileStepExample = {\n  in: getEvent('page view', {\n    timestamp: 1700000000000,\n    data: { title: 'Hello, \"World\"', count: 3 },\n  }),\n  settings: {\n    filename: 'events.csv',\n    format: 'csv',\n    fields: ['timestamp', 'name', 'data'],\n  },\n  out: [\n    [\n      'fs.writeFile',\n      'events.csv',\n      '1700000000000,page view,\"{\"\"title\"\":\"\"Hello, \\\\\"\"World\\\\\"\"\"\",\"\"count\"\":3}\"\\n',\n    ],\n  ],\n};\n"],"mappings":"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","names":["import_dev","import_dev"]}

package/dist/dev.mjs

@@ -0,0 +1 @@
+var e=Object.defineProperty,t=(t,s)=>{for(var a in s)e(t,a,{get:s[a],enumerable:!0})},s={};t(s,{MappingSchema:()=>r,SettingsSchema:()=>i,mapping:()=>m,settings:()=>l});import{zodToSchema as a}from"@walkeros/core/dev";import{z as n}from"@walkeros/core/dev";var i=n.object({filename:n.union([n.string().describe("Static output filename."),n.record(n.string(),n.unknown()).describe('Mapping.Value resolved per event (e.g. { key: "data.tenant" } or { fn: "$code:..." }).')]).describe('Output filename. Static string or Mapping.Value (e.g. { fn: "$code:..." } for daily rotation, { key: "data.tenant" } for sharding).'),format:n.enum(["jsonl","tsv","csv"]).optional().describe("Serialisation format. Defaults to jsonl."),fields:n.array(n.string()).optional().describe("Event paths used as columns for tsv/csv formats. Object values are JSON-stringified. Required when format is tsv or csv.")});import{z as o}from"@walkeros/core/dev";var r=o.object({}).describe("No per-rule overrides for the file destination."),l=a(i),m=a(r),c={};t(c,{env:()=>p,step:()=>u});var p={};function d(){const e={captured:new Map,mkdirCalls:[]};return{_spy:e,fs:{createWriteStream:t=>{const s=e.captured.get(t),a=null!=s?s:{filename:t,lines:[],ended:!1};s||e.captured.set(t,a);return{write:e=>(a.lines.push(e),!0),end(){a.ended=!0}}},mkdir:async t=>{e.mkdirCalls.push(t)}}}}t(p,{init:()=>v,push:()=>f});var v=d(),f=d(),u={};t(u,{csvObjectCell:()=>k,jsonlDailyRotation:()=>b,jsonlDefault:()=>j,jsonlTenantShardKey:()=>h,tsvBaerschLog:()=>w});import{getEvent as g}from"@walkeros/core";var j={in:g("page view",{timestamp:17e11}),settings:{filename:"events.jsonl"},out:[["fs.writeFile","events.jsonl","jsonl:event"]]},w={in:g("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\tsess-1\tpage view\thttps://example.com/docs\tDocs\thttps://example.com/\n"]]},h={in:g("custom event",{timestamp:17e11,data:{tenant:"acme"}}),settings:{filename:{key:"data.tenant"},format:"jsonl"},out:[["fs.writeFile","acme","jsonl:event"]]},b={in:g("order complete",{timestamp:Date.UTC(2026,3,15,12,34,56),data:{id:"ORD-1"}}),settings:{filename:{fn:e=>{var t;const s=null!=(t=e.timestamp)?t:0;return`events-${new Date(s).toISOString().slice(0,10)}.jsonl`}},format:"jsonl"},out:[["fs.writeFile","events-2026-04-15.jsonl","jsonl:event"]]},k={in:g("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{c as examples,s as schemas};//# sourceMappingURL=dev.mjs.map

package/dist/dev.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schemas/index.ts","../src/schemas/settings.ts","../src/schemas/mapping.ts","../src/examples/index.ts","../src/examples/env.ts","../src/examples/step.ts"],"sourcesContent":["import { zodToSchema } from '@walkeros/core/dev';\nimport { SettingsSchema } from './settings';\nimport { MappingSchema } from './mapping';\n\nexport { SettingsSchema, type Settings } from './settings';\nexport { MappingSchema, type Mapping } from './mapping';\n\n// JSON Schema\nexport const settings = zodToSchema(SettingsSchema);\nexport const mapping = zodToSchema(MappingSchema);\n","import { z } from '@walkeros/core/dev';\n\nexport const SettingsSchema = z.object({\n  filename: z\n    .union([\n      z.string().describe('Static output filename.'),\n      z\n        .record(z.string(), z.unknown())\n        .describe(\n          'Mapping.Value resolved per event (e.g. { key: \"data.tenant\" } or { fn: \"$code:...\" }).',\n        ),\n    ])\n    .describe(\n      'Output filename. Static string or Mapping.Value (e.g. { fn: \"$code:...\" } for daily rotation, { key: \"data.tenant\" } for sharding).',\n    ),\n  format: z\n    .enum(['jsonl', 'tsv', 'csv'])\n    .optional()\n    .describe('Serialisation format. Defaults to jsonl.'),\n  fields: z\n    .array(z.string())\n    .optional()\n    .describe(\n      'Event paths used as columns for tsv/csv formats. Object values are JSON-stringified. Required when format is tsv or csv.',\n    ),\n});\n\nexport type Settings = z.infer<typeof SettingsSchema>;\n","import { z } from '@walkeros/core/dev';\n\nexport const MappingSchema = z\n  .object({})\n  .describe('No per-rule overrides for the file destination.');\n\nexport type Mapping = z.infer<typeof MappingSchema>;\n","export * as env from './env';\nexport * as step from './step';\n","import type { Env, FileWriteStream } from '../types';\n\n/**\n * Captured file state for assertions in tests.\n */\nexport interface CapturedFile {\n  filename: string;\n  lines: string[];\n  ended: boolean;\n}\n\n// Narrow helper type aliases so the mock fs is typed explicitly without `any`.\ntype CreateWriteStreamFn = (\n  path: string,\n  options: { flags: string },\n) => FileWriteStream;\ntype MkdirFn = (path: string, options: { recursive: boolean }) => Promise<void>;\n\nexport interface SpyState {\n  captured: Map<string, CapturedFile>;\n  mkdirCalls: string[];\n}\n\nexport interface SpyEnv extends Env {\n  _spy: SpyState;\n}\n\nfunction makeSpyEnv(): SpyEnv {\n  const state: SpyState = {\n    captured: new Map(),\n    mkdirCalls: [],\n  };\n\n  const createWriteStream: CreateWriteStreamFn = (path) => {\n    const existing = state.captured.get(path);\n    const file: CapturedFile = existing ?? {\n      filename: path,\n      lines: [],\n      ended: false,\n    };\n    if (!existing) state.captured.set(path, file);\n    const stream: FileWriteStream = {\n      write(chunk) {\n        file.lines.push(chunk);\n        return true;\n      },\n      end() {\n        file.ended = true;\n      },\n    };\n    return stream;\n  };\n\n  const mkdir: MkdirFn = async (path) => {\n    state.mkdirCalls.push(path);\n  };\n\n  return {\n    _spy: state,\n    fs: {\n      createWriteStream,\n      mkdir,\n    },\n  };\n}\n\nexport const init: SpyEnv = makeSpyEnv();\nexport const push: SpyEnv = makeSpyEnv();\n","import type { Flow } from '@walkeros/core';\nimport { getEvent } from '@walkeros/core';\nimport type { Format } from '../types';\n\n/**\n * Raw filename-config shape accepted in step examples and flow.json.\n * Mirrors the runtime Settings.filename but types `fn` as string so\n * `$code:` tags (resolved at bundle time by walkerOS) are expressible\n * here without casting to a function type.\n */\nexport interface FileSettingsJson {\n  filename:\n    | string\n    | {\n        key?: string;\n        fn?: string | ((value: unknown) => unknown);\n        value?: unknown;\n      };\n  format?: Format;\n  fields?: string[];\n}\n\n/**\n * Extended step example that carries destination-level settings for the\n * file destination.\n *\n * `out` is modeled at intent level as a single `['fs.writeFile', path, line]`\n * tuple per event (even though the destination internally uses a persistent\n * createWriteStream + write). This matches the design doc's preference for\n * readable intent-level callable tuples over stream-chain fidelity.\n *\n * Dropped / ignored events produce `out: []`.\n */\nexport type FileStepExample = Flow.StepExample & {\n  settings: FileSettingsJson;\n};\n\n/** Default JSONL append. Static filename, all defaults. */\nexport const jsonlDefault: FileStepExample = {\n  in: getEvent('page view', { timestamp: 1700000000000 }),\n  settings: { filename: 'events.jsonl' },\n  out: [\n    [\n      'fs.writeFile',\n      'events.jsonl',\n      // JSONL framework contract: JSON.stringify(event) + '\\n'.\n      // The test recomputes this from example.in for the jsonl default to\n      // avoid duplicating the full event shape here.\n      'jsonl:event',\n    ],\n  ],\n};\n\n/** Baersch-style TSV log: PHP parity case. */\nexport const tsvBaerschLog: FileStepExample = {\n  in: getEvent('page view', {\n    timestamp: 1700000000000,\n    data: { title: 'Docs' },\n    user: { session: 'sess-1' },\n    source: {\n      id: 'https://example.com/docs',\n      type: 'server',\n      previous_id: 'https://example.com/',\n    },\n  }),\n  settings: {\n    filename: 'storage/mblog.txt',\n    format: 'tsv',\n    fields: [\n      'timestamp',\n      'user.session',\n      'name',\n      'source.id',\n      'data.title',\n      'source.previous_id',\n    ],\n  },\n  out: [\n    [\n      'fs.writeFile',\n      'storage/mblog.txt',\n      '1700000000000\\tsess-1\\tpage view\\thttps://example.com/docs\\tDocs\\thttps://example.com/\\n',\n    ],\n  ],\n};\n\n/** Tenant sharding via plain key extraction. */\nexport const jsonlTenantShardKey: FileStepExample = {\n  in: getEvent('custom event', {\n    timestamp: 1700000000000,\n    data: { tenant: 'acme' },\n  }),\n  settings: {\n    filename: { key: 'data.tenant' },\n    format: 'jsonl',\n  },\n  out: [['fs.writeFile', 'acme', 'jsonl:event']],\n};\n\n/**\n * Daily rotation via a mapping fn. In flow.json this is authored as a\n * `$code:` string; walkerOS compiles it to a function at bundle time. For\n * in-process tests we pass the already-compiled function directly so the\n * example exercises the same code path without needing the bundler.\n */\nexport const jsonlDailyRotation: FileStepExample = {\n  in: getEvent('order complete', {\n    timestamp: Date.UTC(2026, 3, 15, 12, 34, 56),\n    data: { id: 'ORD-1' },\n  }),\n  settings: {\n    filename: {\n      fn: (value) => {\n        const event = value as { timestamp?: number };\n        const ts = event.timestamp ?? 0;\n        return `events-${new Date(ts).toISOString().slice(0, 10)}.jsonl`;\n      },\n    },\n    format: 'jsonl',\n  },\n  out: [['fs.writeFile', 'events-2026-04-15.jsonl', 'jsonl:event']],\n};\n\n/** CSV with an object cell. data is JSON-stringified, properly quoted. */\nexport const csvObjectCell: FileStepExample = {\n  in: getEvent('page view', {\n    timestamp: 1700000000000,\n    data: { title: 'Hello, \"World\"', count: 3 },\n  }),\n  settings: {\n    filename: 'events.csv',\n    format: 'csv',\n    fields: ['timestamp', 'name', 'data'],\n  },\n  out: [\n    [\n      'fs.writeFile',\n      'events.csv',\n      '1700000000000,page view,\"{\"\"title\"\":\"\"Hello, \\\\\"\"World\\\\\"\"\"\",\"\"count\"\":3}\"\\n',\n    ],\n  ],\n};\n"],"mappings":"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","names":["z"]}

package/dist/examples/index.d.mts

@@ -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 };